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

编程问答

api restful_HATEOAS的RESTful服务。记录超媒体API

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

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

api restful

1.簡介

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

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

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

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

2. OpenAPI和朋友

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

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

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

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

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

就目前而言，超媒體完全破壞了資源位置。超媒體驅動的RESTful Web服務和API并非一成不變，遠非如此，大多數機器或人類需要了解的內容都是在運行時共享的。

3. OpenAPI不是答案，現在呢？

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

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

應用程序級配置文件語義（ALPS）

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

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

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

概要文件的作用是為人類和機器建立共享的結構化詞匯表。簡而言之，概要文件允許定義數據和過渡的語義以及包含文檔的能力。

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

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

在本教程的上半部分，我們已經看到了許多實現RESTful Web服務和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"}} }

與案例研究中的示例相比，您可能會注意到服務器還返回了一個附加的鏈接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" } ] }

到目前為止，我們已經發(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描述符，用于描述數據語義（屬性及其類型）。之后，將引入動作和過渡的描述符數量（ create ， list ， delete ， update ， customer ）。

附帶說明一下，盡管在我們的示例中，概要文件是由應用程序制作的，但是ALPS還具有注冊表概念（ ALPS概要文件注冊表），以允許概要文件定義被重用和引用。已經從schema.org定義中預先構建了大量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 鏈接關系。或者，有時可以看到Links頭對于發(fā)回資源配置文件信息很有用。

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

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

ALPS與JSON-LD，...

一些超媒體規(guī)范對數據語義（詞匯）具有一流的支持。一個很好的例子是帶有@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數據的結構。 JSON Hyper-Schema規(guī)范具有指定超鏈接和與超媒體相關的關鍵字的功能，從而豐富了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提供了更為豐富的語義，用于描述數據，鏈接（關系）和操作（負擔）。以下示例只是為reservation資源構建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ī)范，值得一提。微格式就是其中之一。

微格式是為人為先設計的，其次是為機器設計的，微格式是一組基于現有標準和廣泛采用的標準的簡單，開放的數據格式。微格式并沒有丟掉當今有用的東西，而是首先通過適應當前的行為和使用模式來解決更簡單的問題。

http://microformats.org/wiki/about

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

Microformats2替代并替代了兩種經典的微格式（有時稱為microformats1），并且結合了從微數據和RDFa中獲得的經驗教訓。

http://microformats.org/wiki/microformats2

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

都柏林核心元數據計劃（DCMI）

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

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

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

4。結論

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

5.下一步是什么

在本教程的下一部分中，我們將通過在JVM平臺（使用Java）上設計和實現成熟的RESTful Web服務API，從理論轉向實踐。

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