HATEOAS for REST APIs

What is HATEOAS?

HATEOAS stands for Hypermedia as the Engine of Application State which is a constraint of the REST application architecture.

REST APIs has no service definition and no formal documentation. The best REST APIs don't need any documentation.

Just like websites have navigation from one page to another, REST APIs are able to do the same using HATEOAS.

In HATEOAS the response will carry links that provide links as to where to find the related resources.

This will let clients know all the things they can do with the received response and make the response navigable.

Eg: An user object may contain the URI to itself. 

{
    "name": "John Doe",
    "links": [ {
        "rel": "self",
        "href": "http://localhost:8080/users/1"
    } ]
}

'rel' attribute here defines the relationship.

If we take a status object of a particular social network site, it could be represented as below.

{
   "title": "Hello World",
   "id": 40,
   "author": "John Doe",
   "links": [ {
                "rel": "profile",
                "href": "http://localhost:8080/profiles/1"
            } 
            {
                "rel": "comments",
                "href": "http://localhost:8080/status/40/comments"
            } ]
} 

If the client requires the link to the comments of a particular status it is included here and will help the client navigate easily without having to figure it out.

Similar to how hypertext will navigate us through websites, Hypermedia will drive the client's interaction through the application state and hence called Hypermedia as the Engine of Application State.

This approach is basically how HAL is used in APIs.[2]

When to use it?

HATEOAS is used in hypermedia-driven sites. 

A hypermedia site is a site that contains non linear information(graphics, audio, video etc.). It provides information to navigate the site's REST interfaces dynamically by including hypermedia links in the response.

This approach is not followed in SOA based systems usually as they have a fixed specification.

Why should we use it?

This approach will allow our API consumers know how to navigate through the API without any documentation and will not require them to hard code any URL to any related resource, instead it can be easily taken from the previous response.

How Paypal API uses this approach can be found at [1].

[1] https://developer.paypal.com/docs/api/hateoas-links/
[2] http://stateless.co/hal_specification.html