Why you won't need HATEOAS?

In practice, usually, you probably won't need HATEOAS. Here are the reasons:

  • First of all, implementing and maintaining HATEOAS requires effort on both the server-side and the client-side. The server-side needs to construct the hypertext based on the state of the resource and the clients need to parse the hypertext and understand the meaning of the hypertext to perform the correct operation. Compared with the API without HATEOAS, what you need to do on the client-side is hard-code the URIs of the resources and decide what operations are available based on the representation of the resource. For example, in our ordering coffee example, you can find out which operations among make a payment, update the order, and cancel the order are available based on the value of the status field of an order. In this way, you avoid the overhead introduced by HATEOAS on the server-side and the parsing of hypertext on the client-side.
  • Secondly, the benefit of decoupling the clients with the resources' URIs by adopting HATEOAS isn't bulletproof. The clients still need to know the meanings of the hypertext to find out the operations that can be performed. There is still a coupling between the clients and the hypertext, for example, the update operation in the preceding example standards for updating the order. On the client side, _links.update is used to find the location of the URI for that operation. It is not _links.edit nor _links.modify. This update operation is a simple example and a generic term. For applications that have unique terms for specific operations, the clients need to bind with those terms. And those terms are also subject to change, similar to URIs. The only difference is that they might be changed less frequently as URIs might have to. But still, it doesn't mean that HATEOAS lets you evolve your API independently without causing any effects on the clients. You still need to put lots of effort in to make sure that the terms you use are extensible. Since most of the time changes to APIs are inevitable, we should come up with an API change strategy to manage these changes. That is why even PayPal's API embraces versioning. Currently, they are in version 3. Even NPR's API, which was used as an example stating that APIs don't require versioning, is now adding version numbers in its API URIs (https://dev.npr.org/api/).
  • Thirdly, the self-descriptiveness of an API that hypertext provides through the API's response is partial. That is, you still need to check other documents to find all of the information on the operations that are listed in the hypertext. For example, for the make a payment and update a payment operations, you need to know the representations that you can send to the server, that is, what input parameters those APIs accept, as such information is not revealed in the hypertext. Therefore, for developers of the API clients, they will need to check two places to put together all the pieces of such an API, which is not developer-friendly, making the APIs not easy to use. A more developer-friendly way is to have an API document that provides all of the information developers need to know about the API. An even more pleasant approach is to have a playground so that developers can try it out and see how an API works in action.
  • Fourthly, hypertext can be bypassed. Developers can still use the old URI constructing way to identify resources, ignoring the hypertext in the API response. A way to reduce the misuse of APIs is to provide client libraries for different programming languages. For example, Google Drive's API provides client libraries (https://developers.google.com/drive/api/v3/downloads), even though it doesn't seem to use hypertext and is still called RESTful. As you can see in the following screenshot, in the representation of the file resource, capabilities is used to indicate what the clients can do with this file:
Figure 7.2: The Google Drive API

To sum this up, HATEOAS should be used in places where it can actually help developers of the API clients. For example, the following is a response from the API that can retrieve all of the orders that have been paid. It supports pagination:

{
"items": [{...}],
"paging": {
"previous":
"https://api.examplebucks.org/orders?
page=1&count=20&status=paid",
"next":
"https://api.examplebucks.org/orders?
page=3&count=20&status=paid",
"hasMore": true
}
}

As you can see, by adding the URIs of the previous page and the next page, developers of API clients can go through all of the pages easily without constructing the URIs, which is especially useful for remembering all the query parameters that need to be added to the URI.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.149.250.11