當前位置：首頁 > 编程资源 > 编程问答 >内容正文

编程问答

HATEOAS的RESTful服务。记录超媒体API

發(fā)布時間：2023/12/3 编程问答 35 豆豆

生活随笔收集整理的這篇文章主要介紹了 HATEOAS的RESTful服务。记录超媒体API 小編覺得挺不錯的,現(xiàn)在分享給大家,幫大家做個參考.

1.簡介

希望本教程的前一部分不僅揭示了超媒體和HATEOAS的深遠影響，而且使我們確信這些都是RESTful Web服務(wù)和API的基本構(gòu)建塊。在這一部分中，我們將繼續(xù)側(cè)重于文檔方面，以解決如何預(yù)先傳遞Web服務(wù)或API功能的問題。

在進一步介紹之前，讓我們根據(jù)REST體系結(jié)構(gòu)樣式從服務(wù)提供者和服務(wù)使用者的角度詳細說明手頭的問題。本質(zhì)上，超媒體驅(qū)動的Web服務(wù)和API的可發(fā)現(xiàn)性方面允許服務(wù)提供者發(fā)布單個URL，入口點并以此完成。另一方面，任何意識到超媒體的消費者都應(yīng)該能夠使用上下文鏈接瀏覽資源，并在必要時沿途完成任何所需的狀態(tài)修改。唯一的前提條件是提供者和消費者應(yīng)該說相同的超媒體方言。這是關(guān)于提供者/消費者交互的機器角度，這是探索性客戶端的示例。

現(xiàn)在，讓我們從開發(fā)人員的角度來看這個問題。您將如何知道特定資源的屬性？您如何知道期望使用哪種類型的鏈接和鏈接關(guān)系？它支持的行動或能力如何？它們可能導致什么副作用？最后，作為開發(fā)人員，您只需要滿足一個簡單的要求，例如“客戶C希望將其預(yù)訂R再延長一周”。這是人類對提供者/消費者交互的觀點。

很多具有挑戰(zhàn)性的問題，但是我們有答案嗎？讓我們找出……

2. OpenAPI和朋友

如今，如果我們研究推薦記錄RESTful Web服務(wù)和API的推薦方法是什么，那么您無疑會遇到OpenAPI規(guī)范。規(guī)范有多個版本，但在撰寫本文時，最新版本是3.0.2 。

OpenAPI規(guī)范（ OAS ）為RESTful API定義了一個與語言無關(guān)的標準接口，使人類和計算機都可以發(fā)現(xiàn)和理解服務(wù)的功能，而無需訪問源代碼，文檔或通過網(wǎng)絡(luò)流量檢查。正確定義后，使用者可以使用最少的實現(xiàn)邏輯來理解遠程服務(wù)并與之交互。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

公平地說， OpenAPI是一個很好的規(guī)范，它是許多組織和個人出色的協(xié)作成果的結(jié)果。它已被廣泛認為是記錄RESTful Web服務(wù)和API的首選方法，但它并不是唯一的方法。其他良好的規(guī)范，例如RAML ， API藍圖， RSDL ， WADL ， API Builder ， iodocs和tinyspec也正在使用中，值得了解。

OpenAPI和朋友可以完成這項工作，但是從根本上講，這些規(guī)范集中在資源位置，幾乎沒有或沒有超媒體支持。

就超媒體而言，它完全破壞了資源位置。超媒體驅(qū)動的RESTful Web服務(wù)和API并非是靜態(tài)的，遠非如此，大多數(shù)機器或人類需要了解的內(nèi)容都是在運行時共享的。

3. OpenAPI不是答案，現(xiàn)在呢？

您可能經(jīng)常碰到超媒體將RESTful Web服務(wù)和API轉(zhuǎn)換為資源周圍的狀態(tài)機的說法。從概念上講，這是有道理的，因為超媒體帶來了狀態(tài)和過渡的明確定義的語義。

而不是資源位置，我們應(yīng)該專注于描述資源本身。資源描述至少應(yīng)包括其數(shù)據(jù)語義，受支持的可能動作（狀態(tài)轉(zhuǎn)換）（如果可能，取決于上下文）以及相關(guān)的可導航資源（與關(guān)系類型的鏈接）。

應(yīng)用程序級配置文件語義（ALPS）

應(yīng)用程序級配置文件語義（ ALPS ）可能是最先進的，包含最廣泛的規(guī)范，用于在RESTful Web服務(wù)和API的上下文中記錄和共享超媒體的語義。

ALPS文檔可以用作配置文件，以解釋具有與應(yīng)用程序無關(guān)的媒體類型（例如HTML， HAL ， Collection + JSON ， Siren等）的文檔的應(yīng)用程序語義。這樣可以提高配置文件在各種媒體類型之間的可重用性。

http://www.alps.io/spec/index.html

概要文件的作用是為人類和機器建立共享的結(jié)構(gòu)化詞匯表。簡而言之，概要文件允許定義數(shù)據(jù)的語義和過渡以及包括文檔的能力。

使用通用媒體類型（HTML，Atom， Collection + JSON等）實現(xiàn)超媒體客戶端/服務(wù)器應(yīng)用程序時，客戶端和服務(wù)器實例需要共享對特定于域的信息的理解，例如數(shù)據(jù)元素名稱，鏈接關(guān)系值，和狀態(tài)傳輸參數(shù)。該信息與正在實施的應(yīng)用程序（例如會計，聯(lián)系人管理等）直接相關(guān)，而不是與表示中使用的媒體類型相關(guān)。

http://www.alps.io/spec/index.html

在本教程的上一部分中，我們已經(jīng)看到了許多實現(xiàn)RESTful Web服務(wù)和API的規(guī)范，讓我們嘗試通過ALPS支持來擴展其中之一（例如HAL ）。

$ curl https://rentals.jcg.com/{"_links": {"self": {"href": "https://rentals.jcg.com"},"reservations": {"href": "https://rentals.jcg.com/reservations"},"customers": {"href": "https://rentals.jcg.com/customers"},"profiles": {"href": "https://rentals.jcg.com/alps"}} }

與案例研究中的示例相比，您可能會注意到服務(wù)器還返回了一個附加的鏈接profiles 。讓我們看看它的背后。

$ curl https://rentals.jcg.com/alps{ "version": "1.0", "doc": { "href": "https://rentals.jcg.com/documentation.html" }, "descriptor": [ { "id": "customers", "href": "https://rentals.jcg.com/alps/customers" }, { "id": "reservations", "href": "https://rentals.jcg.com/alps/reservations" } ] }

到目前為止，我們已經(jīng)發(fā)布了兩個配置文件描述符， customers和reservations 。讓我們更深入地了解reservations配置文件描述符。

$ curl https://rentals.jcg.com/alps/reservations{ "version": "1.0", "descriptor": [ { "id": "reservation", "type": "SEMANTIC", "descriptor": [ { "id": "from", "type": "SEMANTIC" "href": "https://schema.org/Date"}, { "id": "id", "type": "SEMANTIC" "href": "https://schema.org/Thing#identifier"}, { "id": "to", "type": "SEMANTIC","href": "https://schema.org/Date"}, { "id": "vehicle", "type": "SEMANTIC","href": "https://schema.org/Vehicle#name"} ] }, { "id": "create", "name": "reservations", "type": "UNSAFE", "rt": "#reservation" }, { "id": "list", "name": "reservations", "type": "SAFE", "rt": "#reservation" }, { "id": "customer", "name": "customer", "type": "SAFE", "href": "https://rentals.jcg.com/alps/customers""rt": "#customer" }, { "id": "update", "name": "reservation", "type": "IDEMPOTENT", "rt": "#reservation" }, { "id": "delete", "name": "reservation", "type": "IDEMPOTENT", "rt": "#reservation" } ] }

值得花一些時間并簡要介紹一下此個人資料。它概述的第一件事是reservation描述符，用于描述數(shù)據(jù)語義（屬性及其類型）。之后，將提供動作和過渡的描述符數(shù)量（ create ， list ， delete ， update ， customer ）。

附帶說明一下，盡管在我們的示例中，概要文件是由應(yīng)用程序制作的，但是ALPS還具有注冊表概念（ ALPS概要文件注冊表），以允許概要文件定義被重用和引用。已經(jīng)從schema.org定義中預(yù)先構(gòu)建了大量ALPS配置文件，并且可以從http://alps.io/schema.org獲得。

回到主題，讓我們看一下使用HAL樣式作為參考的ALPS配置文件如何滲透到資源表示中。

{ "id": "13e1892765c5", "vehicle": "Honda Civic 2020", "from": "2020-01-01", "to": "2020-01-05", "_links": { "profile": { "href": "https://rentals.jcg.com/alps/reservations#reservation" }, "customer": { "href": "https://rentals.jcg.com/customers/fed195a03e9d","profile": "https://rentals.jcg.com/alps/customers#customer"}, "self": { "href": "https://rentals.jcg.com/reservations/13e1892765c5" } }, "_templates": { …} }

HAL文檔已得到充實，以包括指向各自資源配置文件的profile 鏈接關(guān)系。或者，有時可以看到Links頭對于發(fā)送回資源??配置文件信息很有用。

Links: profile="https://rentals.jcg.com/alps/reservations#reservation"

總體而言， ALPS規(guī)范是描述RESTful Web服務(wù)和API的資源語義和轉(zhuǎn)換的一種非常簡單且人性化的方式。

ALPS與JSON-LD，...

一些超媒體規(guī)范對數(shù)據(jù)語義（詞匯）具有一流的支持。一個很好的例子是帶有@vocab上下文定義的JSON-LD 。

{ "@context": { "@vocab": "http://schema.org/" }, "@type": "Reservation", "id": "13e1892765c5", "vehicle": "Honda Civic 2020", "from": "2020-01-01", "to": "2020-01-05", "customer": { "@id": "https://rentals.jcg.com/customers/fed195a03e9d" }, "@id": "https://rentals.jcg.com/reservations/13e1892765c5" }

當依賴超媒體規(guī)范時，資源語義詳細信息將作為資源表示的一部分。無論如何，這是有價值的信息。相反， ALPS配置文件與資源表示形式和媒體類型分開存在，可以獨立查詢和解釋。

JSON超模式

JSON模式是一種基于JSON的格式，用于描述JSON數(shù)據(jù)的結(jié)構(gòu)。 JSON Hyper-Schema規(guī)范具有指定超鏈接和與超媒體相關(guān)的關(guān)鍵字的功能，從而豐富了JSON Schema詞匯表。

JSON Hyper-Schema是一個JSON Schema詞匯表，用于通過超鏈接注釋JSON文檔以及用于通過HTTP等超媒體環(huán)境處理和操縱遠程JSON資源的指令。

https://tools.ietf.org/html/draft-handrews-json-schema-hyperschema-02

與ALPS相比， JSON Hyper-Schema提供了更為豐富的語義，用于描述數(shù)據(jù)，鏈接（關(guān)系）和操作（負擔）。以下示例只是為reservation資源構(gòu)建JSON Hyper-Schema的一種可能性。

{"title": "Reservation","type": "object","properties": {"id": {"title": "Unique Reservation identifier","type": "string"},"vehicle": {"title": "Name of the vehicle","type": "string"},"from": {"title": "Start date","type": "date"},"to": {"title": "End date","type": "date"}},"required" : ["from", "to", "vehicle"],"links": [{"rel": "self","href": "{id}"},{"title": "Customer","rel": "customer","href": "/reservation/{id}/customer"},{"title": "Cancel Reservation","rel": "delete","href": "{id}","method": "DELETE"},{"title": "Update Reservation","rel": "update","href": "{id}","method": "PUT","schema": {"type": "object","properties": {"vehicle": {"title": "Name of the vehicle","type": "string"}, "from": {"title": "Start date","type": "date"},"to": {"title": "End date","type": "date"} },"required": ["vehicle", "to", "from"]}}] }

突出的第一件事可能是每個鏈接和操作所具有的詳細程度。您可能會注意到的直接缺點之一是語義（例如， delete動作）與具體的指針（例如href模板）交織在一起。

微格式

除了ALPS和JSON Hyper-Schema外，還有一些鮮為人知的規(guī)范，值得一提。微格式就是其中之一。

微格式是為人為先設(shè)計的，其次是為機器設(shè)計的，微格式是一組基于現(xiàn)有標準和廣泛采用的標準的簡單，開放的數(shù)據(jù)格式。微格式不是要扔掉今天有用的東西，而是要通過適應(yīng)當前的行為和使用模式來首先解決更簡單的問題。

http://microformats.org/wiki/about

微格式的最新版本稱為microformats2 。

Microformats2取代并取代了兩種經(jīng)典的微格式（有時稱為microformats1），并且結(jié)合了從微數(shù)據(jù)和RDFa中獲得的經(jīng)驗教訓。

http://microformats.org/wiki/microformats2

微格式的主要目標是HTML媒體類型（語義HTML ），因此它不一定最適合大多數(shù)RESTful Web服務(wù)和API。

都柏林核心元數(shù)據(jù)計劃（DCMI）

最初的都柏林核心規(guī)范發(fā)布于1995年，是一組15個（最初為13個）核心元素，用于描述資源語義。因此，都柏林核心元數(shù)據(jù)計劃（ DCMI ）是一個旨在支持跨各種目的和業(yè)務(wù)模型的元數(shù)據(jù)設(shè)計和最佳實踐創(chuàng)新的組織。它定義了更豐富的規(guī)范DCMI元數(shù)據(jù)術(shù)語。

總的來說， Dublin Core是致力于應(yīng)用程序配置文件和鏈接數(shù)據(jù) （尤其是基于RDF詞匯表）的開拓性工作之一。多年來，它所管理的規(guī)范數(shù)量已經(jīng)大大增加，而不僅僅是元數(shù)據(jù)。

與微格式一樣，對于RESTful Web服務(wù)和API來說，都柏林核心和相關(guān)規(guī)范的廣泛范圍可能不是您的首選。

4。結(jié)論

在本教程的這一部分中，我們討論了用豐富的超媒體支持來記錄RESTful Web服務(wù)和API的挑戰(zhàn)。公平地說，這是一個已解決的問題的說法遠非事實。如今， OpenAPI規(guī)范已成為事實上的選擇，但尚未將超媒體視為一流的公民。最突出的替代方案，尤其是應(yīng)用程序級配置文件語義（ALPS）和JSON Hyper-Schema ，無疑正在朝著正確的方向前進，但是，兩者仍在進行中。

5.下一步是什么

在本教程的下一部分中，我們將通過在JVM平臺（使用Java）上設(shè)計和實現(xiàn)成熟的RESTful Web服務(wù)API，從理論轉(zhuǎn)向?qū)嵺`。

翻譯自: https://www.javacodegeeks.com/restful-services-with-hateoas-documenting-hypermedia-apis.html

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎勵來咯，堅持創(chuàng)作打卡瓜分現(xiàn)金大獎

總結(jié)

以上是生活随笔為你收集整理的HATEOAS的RESTful服务。记录超媒体API的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。

上一篇：（linux 进程间通信）
下一篇： central maven_一键发布到M