HATEOAS API: Difference between revisions
Jump to navigation
Jump to search
| (10 intermediate revisions by the same user not shown) | |||
| Line 5: | Line 5: | ||
* It does not allow clients to construct [[URL | URLs]] (unless [[URL Templating | instructed by the server to do so]]) to allow for applications to change their URL structure. | * It does not allow clients to construct [[URL | URLs]] (unless [[URL Templating | instructed by the server to do so]]) to allow for applications to change their URL structure. | ||
* Other than an entry URL and a set of documents describing the [[Media Types]], no additional knowledge should be necessary to use the API. | * Other than an entry URL and a set of documents describing the [[Media Types]], no additional knowledge should be necessary to use the API. | ||
* Having a nice URL structure is not essential, people in browsers will be clicking on links instead of typing and source code should only contain the root URL. | |||
HATEOAS APIs usually make heavy use of HTTP features like: | HATEOAS APIs usually make heavy use of HTTP features like: | ||
* [[Caching]] to enable the application to [[Scaling | scale better]]. | * [[HTTP Caching | Caching]] to enable the application to [[Scaling | scale better]]. | ||
* [[Content Negotiation]] to [[Backward Compatibility | support older clients]] and [[Internationalization | give users localized versions of resources]]. | * [[Content Negotiation]] to [[Backward Compatibility | support older clients]] and [[Internationalization | give users localized versions of resources]]. | ||
* Conditional PUTs to add [[Optimistic Concurrency]]. | * Conditional PUTs to add [[Optimistic Concurrency]]. | ||
== Language Support == | |||
Some programming languages have ready to use libraries that can help you implement a HATEOAS API: | |||
* [[HATEOAS API (Ruby) | Ruby]] | |||
* [[HATEOAS API (NodeJS) | NodeJS]] | |||
== Comparison == | == Comparison == | ||
{| class="wikitable sortable" | {| class="wikitable sortable" | ||
|- | |- | ||
! Method | ! style="background-position: center bottom;padding-right: 0;padding-bottom:21px" | Method | ||
!! style="writing-mode: vertical-rl;" | Browser Accessible | !! style="writing-mode: vertical-rl; background-position: center bottom;padding-right: 0;padding-bottom:21px" | Browser Accessible | ||
!! style="writing-mode: vertical-rl;" | Backward Compatible | !! style="writing-mode: vertical-rl; background-position: center bottom;padding-right: 0;padding-bottom:21px" | Backward Compatible | ||
!! style="writing-mode: vertical-rl;" | Backward Compatible (default) | !! style="writing-mode: vertical-rl; background-position: center bottom;padding-right: 0;padding-bottom:21px" | Backward Compatible (default) | ||
!! style="writing-mode: vertical-rl;" | HTTP Cachable | !! style="writing-mode: vertical-rl; background-position: center bottom;padding-right: 0;padding-bottom:21px" | HTTP Cachable | ||
!! style="writing-mode: vertical-rl;" | No URL Construction | !! style="writing-mode: vertical-rl; background-position: center bottom;padding-right: 0;padding-bottom:21px" | No URL Construction | ||
!! style="writing-mode: vertical-rl;" | URL as Identifier | !! style="writing-mode: vertical-rl; background-position: center bottom;padding-right: 0;padding-bottom:21px" | URL as Identifier | ||
!! style="writing-mode: vertical-rl;" | Stable Pagination | !! style="writing-mode: vertical-rl; background-position: center bottom;padding-right: 0;padding-bottom:21px" | Stable Pagination | ||
!! style="writing-mode: vertical-rl; background-position: center bottom;padding-right: 0;padding-bottom:21px" | Concurrency Support | |||
|- | |||
| HATEOAS || style="background:#fdffb6"|? || style="background:#caffbf"|Yes || style="background:#fdffb6"|? || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#fdffb6"|? || style="background:#caffbf"|Yes | |||
|- | |||
| [https://github.com/XPBytes/media_types-serialization media_types-serialization] (HATEOAS) || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#fdffb6"|? | |||
|- | |||
| [https://docs.github.com/en/free-pro-team@latest/rest/overview/resources-in-the-rest-api Github] (REST) || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#ffadad"|No || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#ffadad"|No | |||
|- | |||
| [https://opensource.zalando.com/restful-api-guidelines/#114 Zalando] || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#ffadad"|No || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes | |||
|- | |||
| [https://developers.facebook.com/docs/graph-api/overview Facebook Graph API] || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#ffadad"|No || style="background:#ffadad"|No || style="background:#ffadad"|No || style="background:#fdffb6"|? || style="background:#ffadad"|No | |||
|- | |- | ||
| | | [https://shopify.dev/docs/admin-api/rest Shopify] (REST) || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#ffadad"|No || style="background:#ffadad"|No || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#ffadad"|No | ||
|- | |- | ||
| | | GraphQL || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#ffadad"|No || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#ffadad"|No | ||
|- | |- | ||
| [https:// | | [https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md Microsoft] || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#ffadad"|No || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes | ||
|- | |- | ||
| [https:// | | [https://cloud.google.com/apis/design Google] || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#ffadad"|No || style="background:#ffadad"|No || style="background:#caffbf"|Yes || style="background:#caffbf"|Yes | ||
|} | |} | ||
[[Category: Terminology]] | [[Category: Terminology]] | ||
Latest revision as of 05:58, 19 January 2021
Originally called REST, HATEOAS is a way of designing HTTP APIs as described in Roy Fieldings thesis. The acronym stands for Hypermedia as the Engine of Application State.
It distinguishes itself from other APIs by having the following properties:
- Heavy use of Media Types to allow Backward Compatibility.
- It does not allow clients to construct URLs (unless instructed by the server to do so) to allow for applications to change their URL structure.
- Other than an entry URL and a set of documents describing the Media Types, no additional knowledge should be necessary to use the API.
- Having a nice URL structure is not essential, people in browsers will be clicking on links instead of typing and source code should only contain the root URL.
HATEOAS APIs usually make heavy use of HTTP features like:
- Caching to enable the application to scale better.
- Content Negotiation to support older clients and give users localized versions of resources.
- Conditional PUTs to add Optimistic Concurrency.
Language Support
Some programming languages have ready to use libraries that can help you implement a HATEOAS API:
Comparison
| Method | Browser Accessible | Backward Compatible | Backward Compatible (default) | HTTP Cachable | No URL Construction | URL as Identifier | Stable Pagination | Concurrency Support |
|---|---|---|---|---|---|---|---|---|
| HATEOAS | ? | Yes | ? | Yes | Yes | Yes | ? | Yes |
| media_types-serialization (HATEOAS) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | ? |
| Github (REST) | Yes | Yes | No | No | Yes | Yes | Yes | No |
| Zalando | No | Yes | Yes | No | No | Yes | Yes | Yes |
| Facebook Graph API | Yes | Yes | Yes | No | No | No | ? | No |
| Shopify (REST) | Yes | Yes | Yes | No | No | No | Yes | No |
| GraphQL | No | Yes | No | No | Yes | No | Yes | No |
| Microsoft | Yes | Yes | Yes | Yes | No | No | Yes | Yes |
| Yes | Yes | No | Yes | No | No | Yes | Yes |