HATEOAS (Hypermedia As The Engine of Application State)

Hypermedia As The Engine of Application State (HATEOAS) is a constraint of the REST architecture known as the uniform interface constraint.

Using HATEOAS, servers provide self-described APIs through hypermedia, which decouples client and server and enables functionality to evolve without separate documentation or versioning.

Example

Following HTML response carries along all API information necessary to continue interacting with the system directly within itself (depositing, transferring, etc.), thus making it the engine of application state.

HTTP/1.1 200 OK

<html>
    <body>
        <div>Account number: 12345</div>
        <div>Balance: $100.00 USD</div>
        <div>Links:
            <a href="/accounts/12345/deposits">deposits</a>
            <a href="/accounts/12345/withdrawals">withdrawals</a>
            <a href="/accounts/12345/transfers">transfers</a>
            <a href="/accounts/12345/close-requests">close-requests</a>
        </div>
    <body>
</html>

The JSON response on the other hand is not self describing, since the client must know how to display the information and what actions are available, all derived from outside the response (e.g. swagger API documentation, etc.). This makes it a RPC style of API, where client and server are coupled.

HTTP/1.1 200 OK

{
    "account_number": 12345,
    "balance": {
        "currency": "usd",
        "value": 100.00
     },
     "status": "good"
}

Advantages:

Enter RESTful system through a single URL entrypoint
Actions taken within are then provided through self-describing hypermedia
Thus, no need to version or even document the API

Resources

HATEOAS - An Alternative Explanation.