當(dāng)前位置：首頁(yè) > 编程资源 > 编程问答 >内容正文

编程问答

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

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

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

api restful

1.簡(jiǎn)介

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

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

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

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

2. OpenAPI和朋友

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

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

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

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

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

就目前而言，超媒體完全破壞了資源位置。超媒體驅(qū)動(dòng)的RESTful Web服務(wù)和API并非一成不變，遠(yuǎn)非如此，大多數(shù)機(jī)器或人類(lèi)需要了解的內(nèi)容都是在運(yùn)行時(shí)共享的。

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

您可能經(jīng)常碰到超媒體將RESTful Web服務(wù)和API轉(zhuǎn)換為資源周?chē)臓顟B(tài)機(jī)的說(shuō)法。從概念上講，這是有道理的，因?yàn)槌襟w帶來(lái)了狀態(tài)和過(guò)渡的明確定義的語(yǔ)義。

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

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

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

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

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

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

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

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

在本教程的上半部分，我們已經(jīng)看到了許多實(shí)現(xiàn)RESTful Web服務(wù)和API的規(guī)范，讓我們嘗試通過(guò)ALPS支持來(lái)擴(kuò)展其中之一（例如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"}} }

與案例研究中的示例相比，您可能會(huì)注意到服務(wù)器還返回了一個(gè)附加的鏈接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ā)布了兩個(gè)配置文件描述符， 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" } ] }

值得花一些時(shí)間并簡(jiǎn)要介紹一下此個(gè)人資料。它概述的第一件事是reservation描述符，用于描述數(shù)據(jù)語(yǔ)義（屬性及其類(lèi)型）。之后，將引入動(dòng)作和過(guò)渡的描述符數(shù)量（ create ， list ， delete ， update ， customer ）。

附帶說(shuō)明一下，盡管在我們的示例中，概要文件是由應(yīng)用程序制作的，但是ALPS還具有注冊(cè)表概念（ ALPS概要文件注冊(cè)表），以允許概要文件定義被重用和引用。已經(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文檔已得到充實(shí)，包括指向各自資源配置文件的profile 鏈接關(guān)系。或者，有時(shí)可以看到Links頭對(duì)于發(fā)回資源配置文件信息很有用。

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

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

ALPS與JSON-LD，...

一些超媒體規(guī)范對(duì)數(shù)據(jù)語(yǔ)義（詞匯）具有一流的支持。一個(gè)很好的例子是帶有@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" }

當(dāng)依賴(lài)超媒體規(guī)范時(shí)，資源語(yǔ)義詳細(xì)信息將作為資源表示的一部分。無(wú)論如何，這是有價(jià)值的信息。相反， ALPS概要文件與資源表示形式和媒體類(lèi)型分開(kāi)存在，并且可以獨(dú)立查詢和解釋。

JSON超模式

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

JSON Hyper-Schema是一個(gè)JSON Schema詞匯表，用于使用超鏈接注釋JSON文檔以及通過(guò)HTTP等超媒體環(huán)境處理和操縱遠(yuǎn)程JSON資源的說(shuō)明。

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

與ALPS相比， JSON Hyper-Schema提供了更為豐富的語(yǔ)義，用于描述數(shù)據(jù)，鏈接（關(guān)系）和操作（負(fù)擔(dā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"]}}] }

突出的第一件事可能是每個(gè)鏈接和操作所具有的詳細(xì)程度。您可能會(huì)注意到的直接缺點(diǎn)之一是語(yǔ)義（例如， delete動(dòng)作）與具體的指針（例如href模板）交織在一起。

微格式

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

微格式是為人為先設(shè)計(jì)的，其次是為機(jī)器設(shè)計(jì)的，微格式是一組基于現(xiàn)有標(biāo)準(zhǔn)和廣泛采用的標(biāo)準(zhǔn)的簡(jiǎn)單，開(kāi)放的數(shù)據(jù)格式。微格式并沒(méi)有丟掉當(dāng)今有用的東西，而是首先通過(guò)適應(yīng)當(dāng)前的行為和使用模式來(lái)解決更簡(jiǎn)單的問(wèn)題。

http://microformats.org/wiki/about

微格式的最新版本稱(chēng)為microformats2 。

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

http://microformats.org/wiki/microformats2

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

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

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

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

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

4。結(jié)論

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

5.下一步是什么

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

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