api restful

1.簡介

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

目錄

1.簡介 2. OpenAPI和朋友 3. OpenAPI不是答案，現(xiàn)在呢？

3.1。 應(yīng)用程序級配置文件語義（ALPS） 3.2。 ALPS與JSON-LD，... 3.3。 JSON超模式 3.4。 微格式 3.5。 都柏林核心元數(shù)據(jù)計劃（DCMI）

4。結(jié)論 5.下一步是什么

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

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

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

2. OpenAPI和朋友

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

與案例研究中的示例相比，您可能會注意到服務(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文檔已得到充實(shí)，包括指向各自資源配置文件的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" }

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

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)境處理和操縱遠(yuǎn)程JSON資源的說明。

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

與ALPS相比， JSON Hyper-Schema提供了更為豐富的語義，用于描述數(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"]}}] }

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

微格式

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

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

http://microformats.org/wiki/about

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

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

http://microformats.org/wiki/microformats2

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

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

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

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

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

4。結(jié)論

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

5.下一步是什么

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

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

api restful

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

總結(jié)

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

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