Skip to content

Latest commit

 

History

History
28 lines (18 loc) · 2.27 KB

hypermedia-and-rest.md

File metadata and controls

28 lines (18 loc) · 2.27 KB

##Hypermedia and REST There are four different Levels in the REST API Evolution. They are described in the Richardson Maturity Model. You can find more informatiion in this article from Martin Fowler.

Hypermedia represents the links to your API. The main characteristics of Hypermedia are:

  • Decouple the Server and the Client
  • Links are to help developers know how to use the API
    • The developer interacts with the first URL
    • The Navigation is controlled by the server
  • API becomes self-describing
  • Links become the application state
  • HATEOAS

(HATEOAS) Hypermedia as the Engine of Application State. The principle of addressability just says that every > resource should have its own URL. If something is important to your application, it should have a unique name, a > URL, so that you and your users can refer to it unambiguously.

The URI Templates for HATEOAS are covered in RFC 6570 and the Link Header in RFC 5988.

At its core, HATEAOAS provides a way to interact with the REST API entirely through hyperlinks. With each call that you make to the API, we’ll return an array of links that allow you to request more information about a call and to further interact with the API. You no longer need to hard code the logic necessary to use the REST API.

HATEOAS links are contextual, so you only get the information that is relative to a specific request.

Details about Hypermedia formats are described in Response Formats.

###Relative vs Absolute

It is strongly recommended that the URLs generated by the API should be absolute URLs.

The reason is mostly for ease of use by the client, so that it never has to find out the correct base URI for a resource, which is needed to interpret a relative URL. The URL RFC specifies the algorithm for determining a base URL, which is rather complex. One of the options for finding the base URL is to use the URL of the resource that was requested. Since a resource may appear under multiple URLs (for example, as part of a collection, or stand-alone), it would be a significant overhead to a client to remember where he retrieved a representation from. By using absolute URLs, this problem doesn’t present itself.