by Sanchit Gera

通過(guò)Sanchit Gera

RESTful服務(wù)的第三部分：HATEOAS和Richardson成熟度模型 (RESTful Services Part III : HATEOAS and The Richardson Maturity Model)

In Part I of this series, you learned the very basics of HTTP. We went over common HTTP constructs such as headers, URLs and the different status codes available. We also looked at how each of these constructs could be useful when building resource-oriented web services.

在本系列的第一部分中，您學(xué)習(xí)了HTTP的基礎(chǔ)知識(shí)。 我們介紹了常見(jiàn)的HTTP結(jié)構(gòu)，例如標(biāo)頭，URL和可用的不同狀態(tài)代碼。 我們還研究了在構(gòu)建面向資源的Web服務(wù)時(shí)這些構(gòu)造中的每個(gè)構(gòu)造如何有用。

In Part II, you learned about the different constraints you need to comply with in order to build scalable, high-performance RESTful systems.

在第二部分中 ，您了解了為了構(gòu)建可擴(kuò)展的高性能RESTful系統(tǒng)需要遵守的各種約束。

This post will provide you with the third and final piece of the puzzle. As noted before, REST is not a standard, but rather an abstract concept. This makes it hard to quantify exactly how “RESTful” a service is or isn’t.

這篇文章將為您提供難題的第三篇也是最后一部分。 如前所述，REST不是標(biāo)準(zhǔn)，而是抽象概念。 這使得很難準(zhǔn)確地量化服務(wù)是否是“ RESTful”的。

While the constraints discussed in the previous part are helpful when creating a service, they aren’t as good at solving this problem. What if you chose to follow exactly one of those constraints? Two? Three? At what point does your service stop being partially RESTful and cross over into the magical land of complete RESTful-ness?

雖然上一部分中討論的約束在創(chuàng)建服務(wù)時(shí)很有用，但它們并不能很好地解決此問(wèn)題。 如果您選擇完全遵循這些約束之一怎么辦？ 二？ 三？ 在什么時(shí)候，您的服務(wù)會(huì)停止部分地成為 RESTful并跨入完全 RESTful-ness的魔境？

This is exactly the problem that the Richardson Maturity Model (RMM) helps you solve. But before we dive further into the nitty gritty of RMM, there’s one final topic that will prove to be useful in your understanding of REST.

這正是Richardson成熟度模型(RMM)可以幫助您解決的問(wèn)題。 但是，在我們進(jìn)一步深入研究RMM的本質(zhì)之前，有一個(gè)最后的主題對(duì)您理解REST很有用。

HATEOAS原理 (The Principle of HATEOAS)

Hypermedia As The Engine Of Application State, shortened to HATEOAS, builds on one of the constraints of REST (the Uniform Interface). I am still trying to determine how to pronounce it. I usually alternate between Hate-ee-ose and Hate-ose. Feel free to choose either, or come up with your own. But anyway, I digress.

?ypermedia 甲 式T他?ngine?F A pplication 小號(hào)泰特，縮短到HATEOAS，建立在REST的約束中的一個(gè)( 統(tǒng)一的接口 )。 我仍在嘗試確定如何發(fā)音。 我通常會(huì)在“討厭的人”和“討厭的人”之間切換。 隨意選擇，或者提出自己的想法。 但是無(wú)論如何，我離題了。

The overarching goal behind HATEOAS is to provide a consistent way for machines to understand APIs and navigate them without having any information about them beforehand, identical to a user visiting a website for the first time.

HATEOAS的總體目標(biāo)是為機(jī)器提供一致的方式來(lái)理解API和瀏覽API，而無(wú)需事先獲得有關(guān)API的任何信息，這與首次訪問(wèn)網(wǎng)站的用戶相同。

Assume you were visiting Medium for the first time to write a post. What steps would you take? In all likelihood, you would visit Medium’s homepage, head over to the Stories section, and begin writing your masterpiece. You aren’t really concerned with the URL that Stories section lives on. You don’t have it memorized, but you know that you will be able to get there when you need to.

假設(shè)您是第一次訪問(wèn)Medium寫(xiě)一篇文章。 您將采取什么步驟？ 您很可能會(huì)訪問(wèn)Medium的主頁(yè)，轉(zhuǎn)到“ 故事”部分，然后開(kāi)始撰寫(xiě)您的杰作。 您實(shí)際上并不關(guān)心“ 故事”部分所依據(jù)的URL。 您沒(méi)有記住它，但是您知道您將可以在需要時(shí)到達(dá)那里。

Or imagine you were ordering something on Amazon. You go in, search for different items, add them to the cart, and checkout. The location of each of these components within the system is inconsequential to you as a user. If the URL required to get to the cart, there is a strong chance you wouldn’t even find out. And yet, your experience remains unhampered.

或想象您正在亞馬遜上訂購(gòu)商品。 您進(jìn)去，搜索其他項(xiàng)目，將它們添加到購(gòu)物車，然后結(jié)帳。 這些組件中每個(gè)組件在系統(tǒng)中的位置對(duì)于您來(lái)說(shuō)都是無(wú)關(guān)緊要的。 如果需要購(gòu)物車的網(wǎng)址，很有可能您根本找不到。 但是，您的經(jīng)驗(yàn)仍然沒(méi)有受到阻礙。

In both cases, you only need a single piece of information, that is the entry point to the website. Everything else from that point on is completely discoverable and usable by navigating relevant links (aka hypermedia). This is how the web is designed to work and indeed how most users experience it today.

在這兩種情況下，您只需要一條信息，即網(wǎng)站的入口點(diǎn)。 從那時(shí)起，通過(guò)導(dǎo)航相關(guān)鏈接(也稱為超媒體) ，可以完全發(fā)現(xiàn)并使用所有其他內(nèi)容。 這就是設(shè)計(jì)網(wǎng)絡(luò)工作方式的方式，實(shí)際上也是當(dāng)今大多數(shù)用戶的體驗(yàn)方式。

HATEOAS extends this idea of discoverability to APIs and web services as well. What if, given a single point of access to the service, I could make use of everything that it has to offer? Luckily, this can be achieved by exploiting the resource oriented nature of our data that we have been working so hard on!

HATEOAS還將可發(fā)現(xiàn)性的思想擴(kuò)展到了API和Web服務(wù)。 如果在單點(diǎn)訪問(wèn)服務(wù)的情況下，我可以利用其所提供的一切，該怎么辦？ 幸運(yùn)的是，這可以通過(guò)利用我們一直在努力的數(shù)據(jù)的面向資源的本質(zhì)來(lái)實(shí)現(xiàn)！

We know that since everything being returned by our service is essentially a resource, there are only a handful of things that our service consumer can do with that resource. Further, each action corresponds to a well defined RESTful route within our system (think GET, POST, PUT etc.). This means that we could easily embed all potential interactions with a given resource in the form of actionable URLs within the response. Let’s see an example!

我們知道，由于我們的服務(wù)所返回的所有內(nèi)容本質(zhì)上都是一種資源，因此，我們的服務(wù)使用者只能使用該資源做一些事情。 此外，每個(gè)動(dòng)作都對(duì)應(yīng)于我們系統(tǒng)中定義良好的RESTful路由(請(qǐng)考慮GET，POST，PUT等)。 這意味著我們可以輕松地在響應(yīng)中以可操作的URL形式嵌入與給定資源的所有潛在交互。 讓我們來(lái)看一個(gè)例子！

Let’s return to our previous example of writing a story on Medium. Imagine if instead of a user-facing website, it was instead purely a web service. Under the HATEOAS model, the only piece of information to navigate the service I need would be the hostname: medium.com

讓我們回到前面的例子中，該故事在Medium上寫(xiě)。 想象一下，如果它不是面向用戶的網(wǎng)站，而是純粹的Web服務(wù)。 在HATEOAS模型下，導(dǎo)航我需要的服務(wù)的唯一信息就是主機(jī)名： medium.com

I begin my interaction by making a GET request to the host. Medium promptly responds with a list of all the resources it has to offer, along with where I can find them.

我通過(guò)向主機(jī)發(fā)出GET請(qǐng)求開(kāi)始交互。 中型會(huì)Swift響應(yīng)并列出所有它必須提供的資源，以及在哪里可以找到它們。

GET medium.comlinks : [ { rel : "bookmarks", href : "/bookmarks" }, { rel : "stories", href: "/stories" }]

In this simplified version of Medium, I’m told that there are two resources being offered: stories and bookmarks. I’m also told where each of those resources lives on the system.

在此簡(jiǎn)化版的Medium中，我被告知提供了兩種資源： 故事和書(shū)簽。 還告訴我這些資源中的每一個(gè)在系統(tǒng)上的位置。

Next, I need to figure out how to create a new story. From our previous discussions, I already know that this is going to be a POST request, but as a client I still don’t know what kind of data the service is expecting for this request. This is exactly where an OPTIONS request comes in handy. So lets do just that!

接下來(lái)，我需要弄清楚如何創(chuàng)建一個(gè)新故事。 從前面的討論中，我已經(jīng)知道這將是一個(gè)POST請(qǐng)求，但是作為客戶端，我仍然不知道該服務(wù)期望該請(qǐng)求使用哪種數(shù)據(jù)。 這正是OPTIONS請(qǐng)求派上用場(chǎng)的地方。 因此，讓我們做到這一點(diǎn)！

OPTIONS medium.com/storiesAllow GET, POST{ name : "Stories", description: "Ideas and opinions from around the world", actions: [ { POST: { title: "string", body: "string" } } ]}

Aha! Looks like we need parameters named title and body corresponding to our new post. This gives us all the information that we need. We can now go ahead and start POSTing to the service and creating new articles on the service.

啊哈！ 看起來(lái)我們需要與我們的新帖子相對(duì)應(yīng)的名為title和body的參數(shù)。 這為我們提供了所需的所有信息。 現(xiàn)在，我們可以開(kāi)始發(fā)布服務(wù)，并在服務(wù)上創(chuàng)建新文章。

Now let’s say that following this approach, I land on an existing story. What would an individual story look like?

現(xiàn)在讓我們說(shuō)，按照這種方法，我著眼于一個(gè)已有的故事。 個(gè)人故事會(huì)是什么樣？

GET medium.com/stories/3{ "id": 3, "title": "An Introduction to Microservices", "body": "...", "created_at": "2016-10-25T20:52:12.804Z", "links": [ { "rel": "self", "href": "/stories/1" }, { "rel": "author", "href": "/authors/3" }, { "rel": "comments", "href": "/stories/3/comments" }],}

Now I not only have information about the story, but I also have a means of getting information about the author and the comments.

現(xiàn)在，我不僅可以獲得有關(guān)故事的信息，而且還可以獲取有關(guān)作者和評(píng)論的信息。

Of course, this is overly simplistic. There are tons of other things going on such as authentication and authorization that need to be taken care of. And a lot of work needs to be done to design systems that are decomposable into resources this easily. But it serves well to understand the idea behind HATEOAS.

當(dāng)然，這過(guò)于簡(jiǎn)單了。 還有很多其他事情需要進(jìn)行，例如身份驗(yàn)證和授權(quán)。 要設(shè)計(jì)可輕松分解為資源的系統(tǒng)，需要做大量的工作。 但是，了解HATEOAS背后的想法非常有用。

This eliminates the need for you as a developer to maintain documentation for your service. Everything a client could possibly need to know about using your service is already in there.

這消除了您作為開(kāi)發(fā)人員維護(hù)服務(wù)文檔的需要。 客戶可能需要知道的有關(guān)使用您的服務(wù)的所有信息。

Similarly, as a client, I do not need to keep track of the URLs associated with each of these resources. I look for the object corresponding to the resource, and navigate to it. If it changes, I don’t care.

同樣，作為客戶端，我不需要跟蹤與這些資源中的每一個(gè)相關(guān)的URL。 我尋找與資源相對(duì)應(yīng)的對(duì)象，然后導(dǎo)航到它。 如果改變了，我不在乎。

With this in mind, let’s now shift our focus to the Richardson Maturity Model (RMM).

考慮到這一點(diǎn)，現(xiàn)在讓我們將重點(diǎn)轉(zhuǎn)移到Richardson成熟度模型(RMM)。

理查森成熟度模型 (The Richardson Maturity Model)

As mentioned previously, RMM is a tool to help you evaluate how RESTful a service is. This system of classification — first described by Leonard Richardson — provides a neat way to think about your web services from the perspective of an end user, then make judgments accordingly.

如前所述，RMM是幫助您評(píng)估服務(wù)的RESTful程度的工具。 這種分類系統(tǒng)(首先由Leonard Richardson描述)提供了一種從最終用戶的角度考慮Web服務(wù)并進(jìn)行相應(yīng)判斷的巧妙方法。

Richardson describes four distinct levels in the spectrum of RESTful-ness.

理查森(Richardson)描述了RESTful-ness范圍中的四個(gè)不同級(jí)別。

0級(jí) (Level 0)

This is rock bottom when it comes to a service being RESTful. Services in this category follow the “one URL, one method” principle. That means, the service only exposes a single URL to the outside world and accepts only one type of request (usually POST) at that location.

當(dāng)涉及到RESTful服務(wù)時(shí)，這是最基本的。 此類服務(wù)遵循“一個(gè)URL，一種方法”的原則。 這意味著該服務(wù)僅向外界公開(kāi)一個(gè)URL，并且在該位置僅接受一種類型的請(qǐng)求(通常為POST)。

This is typical for SOAP services for example. A typical request to a SOAP service looks something like this:

例如，這對(duì)于SOAP服務(wù)是典型的。 對(duì)SOAP服務(wù)的典型請(qǐng)求如下所示：

POST /Quotation HTTP/1.0Host: www.xyz.orgContent-Type: text/xml; charset=utf-8Content-Length: nnn<?xml version="1.0"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2001/12/soap-envelope" SOAP-ENV:encodingStyle="http://www.w3.org/2001/12/soap-encoding" > <SOAP-ENV:Body xmlns:m="http://www.xyz.org/quotations" > <m:GetQuotation> <m:QuotationsName>MiscroSoft</m:QuotationsName> </m:GetQuotation> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Everything is described in the body of the request, including the action (getQuotation) and the parameters for that request (Microsoft). Clearly, the service does not make use of any of the REST principles we have discussed thus far, not to mention the cost of having a whole other additional data format on top of HTTP.

在請(qǐng)求的主體中描述了所有內(nèi)容，包括操作(getQuotation)和該請(qǐng)求的參數(shù)(Microsoft)。 顯然，該服務(wù)未利用我們到目前為止討論的任何REST原理，更不用說(shuō)在HTTP之上具有其他所有附加數(shù)據(jù)格式的成本。

級(jí)別1：資源 (Level 1: Resources)

The next step on our path to complete RESTful-ness is introducing resources based abstractions. This is the equivalent of breaking up the application into distinct resource specific URLs. It’s characterized by Richardson as the “Multiple URLs, One Method” implementation.

完成RESTful-ness的下一步是引入基于資源的抽象。 這相當(dāng)于將應(yīng)用程序分解為不同的資源特定的URL。 理查森(Richardson)將其稱為“多個(gè)URL，一種方法”實(shí)施。

Here, there are several different URLs in the system working together to provide the desired functionality. But each accepts only one type of requests (again, usually POST).

在這里，系統(tǒng)中有幾個(gè)不同的URL協(xié)同工作以提供所需的功能。 但是每個(gè)都只接受一種類型的請(qǐng)求(同樣，通常是POST)。

So for example, continuing our previous example, we can proceed to first retrieve a list of all companies from our application:

因此，例如，繼續(xù)前面的示例，我們可以首先從應(yīng)用程序中檢索所有公司的列表：

POST /companies[ { "name" : "Microsoft", "id" : 3 }, { "name" : "Apple", "id" : 4 }]

…and then get a quotation for a single company:

…然后獲得一家公司的報(bào)價(jià)：

POST /quotations/3{ quotation: {}}

This is definitely a step up from before. In fact, this is how a lot of applications had been written until REST gained popularity. But again, we aren’t utilizing the strengths of HTTP. We can do better!

這絕對(duì)是從前的一步。 實(shí)際上，這就是在REST流行之前編寫(xiě)許多應(yīng)用程序的方式。 但同樣，我們沒(méi)有利用HTTP的優(yōu)勢(shì)。 我們可以做得更好！

2級(jí)：動(dòng)詞 (Level 2: Verbs)

Now we throw the concept of action verbs into the mix. In addition to having well defined resources, the actions that can be performed on a resource must strictly follow HTTP conventions.

現(xiàn)在，我們將動(dòng)作動(dòng)詞的概念混入其中。 除了擁有定義明確的資源外，可對(duì)資源執(zhí)行的操作還必須嚴(yán)格遵循HTTP約定。

A GET MUST not modify the resource state, a POST MUST only be used for resource creation, and so on. It is characterized as, of course, the “Many URLs, Many Actions” system.

GET絕不能修改資源狀態(tài)，POST只能用于資源創(chuàng)建，依此類推。 它的特征當(dāng)然是“許多URL，許多操作”系統(tǒng)。

This brings us to the services most of us are familiar with and use on a day to day basis. These are also the kind of services that we usually consider RESTful. However, there is one more level that services must conform to in order to achieve the coveted status of complete RESTfulness.

這使我們獲得了我們大多數(shù)人每天都熟悉和使用的服務(wù)。 這些也是我們通常認(rèn)為是RESTful的服務(wù)。 但是，服務(wù)必須達(dá)到一個(gè)更高的級(jí)別，才能達(dá)到令人羨慕的完全RESTful狀態(tài)。

第3級(jí)：HATEOAS (Level 3: HATEOAS)

This is where most services fall short. The vast majority of APIs and web services that you encounter as a developer, or likely ones that you will work on likely don’t follow the principle of HATEOAS.

這是大多數(shù)服務(wù)不足的地方。 作為開(kāi)發(fā)人員或您將要使用的開(kāi)發(fā)人員遇到的絕大多數(shù)API和Web服務(wù)可能都不遵循HATEOAS的原理。

Most service providers still prefer to document their services traditionally, by providing developers with a list of available endpoints along with some information on how to interact with that endpoint. Here’s the Twitter REST API, for example. (Interestingly, the PayPal API strongly pushes for Hypermedia Controls.)

大多數(shù)服務(wù)提供商仍然喜歡通過(guò)傳統(tǒng)方式記錄其服務(wù)，方法是為開(kāi)發(fā)人員提供可用端點(diǎn)的列表以及有關(guān)如何與該端點(diǎn)進(jìn)行交互的一些信息。 例如，這是Twitter REST API 。 (有趣的是，PayPal API 強(qiáng)烈推動(dòng)了超媒體控件。)

This isn’t necessarily bad. There are some good arguments to be made both in favor of and against utilizing HATEOAS. While on the one hand it makes APIs easy to discover and use, that usually comes at the cost of more development time and effort.

這不一定是壞事。 無(wú)論是贊成還是反對(duì)利用HATEOAS，都有一些很好的論據(jù)。 一方面，它使API易于發(fā)現(xiàn)和使用，但通常以花費(fèi)更多的開(kāi)發(fā)時(shí)間和精力為代價(jià)。

In fact, if all you need to do is make a single call to the API, introducing HATEOAS may actually make things more difficult for you as a consumer.

實(shí)際上，如果您需要做的只是對(duì)API的一次調(diào)用，那么引入HATEOAS可能實(shí)際上會(huì)使您作為消費(fèi)者變得更加困難。

結(jié)論 (Conclusion)

At the end of the day, these measures aren’t something you need to be swear by. REST, along with all it’s constraints, is merely a tool in your tool belt when building web services and applications. It’s entirely up to you to take from it what best fits your needs.

歸根結(jié)底，這些措施并不是您需要保證的。 REST及其所有約束條件，在構(gòu)建Web服務(wù)和應(yīng)用程序時(shí)只是工具帶中的工具。 完全取決于您的需求，這完全取決于您。

I hope you learned a lot of useful concepts from this series. If you’re looking to create a RESTful web service to supplement your next project, or looking to work with an existing one, you should now have a good understanding of some of the rationales behind them.

希望您從本系列中學(xué)到了許多有用的概念。 如果您希望創(chuàng)建一個(gè)RESTful Web服務(wù)來(lái)補(bǔ)充您的下一個(gè)項(xiàng)目，或者希望與現(xiàn)有的項(xiàng)目一起使用，那么您現(xiàn)在應(yīng)該對(duì)它們背后的一些原理有很好的了解。

Here are the links to the previous parts, in case you missed them:

如果您錯(cuò)過(guò)了它們，以下是前幾部分的鏈接：

RESTful Services Part I: HTTP in a Nutshell

RESTful服務(wù)的第一部分：簡(jiǎn)而言之的HTTP

RESTful Services Part II: Constraints and Goals

RESTful服務(wù)第二部分：約束和目標(biāo)

Let me know what you thought of this post in the comments, or contact me via LinkedIn.

在評(píng)論中讓我知道您對(duì)此帖子的看法，或者通過(guò)LinkedIn與我聯(lián)系。

Don’t forget to hit the ? if you enjoyed this article.

別忘了打嗎？ 如果您喜歡這篇文章。

Cheers and happy learning!

祝您學(xué)習(xí)愉快！

More Resources

更多資源

• Martin Fowler’s Blog

  馬丁·福勒的博客

• Leonard Richardson’s presentation

  倫納德·理查森(Leonard Richardson)的演講

• SOAP example borrowed from TutorialsPoint

  從TutorialsPoint借用的SOAP示例

翻譯自: https://www.freecodecamp.org/news/restful-services-part-iii-hateoas-and-the-richardson-maturity-model-48d4e4c79b8d/

總結(jié)

以上是生活随笔為你收集整理的RESTful服务的第三部分：HATEOAS和Richardson成熟度模型的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

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