HATEOAS
Hypermedia as the Engine of Application State

Basically, HATEOAS allows to interact with a REST api without knowing it first. Let’s say we have a known entry point for some user and we call GET to retrieve a specific user. What we get in a response, are follow-up links that can be called to further interact with the API.

User entrypoint
GET https://myservice/user/69

We then receive a response with following body

Response containing follow-up links
{
    "user": {
        "name": "Ben Dover",
        "address": {
            "street": "Square st. 25",
            "city": "Godham",
            "country": "Paradiseland"
        },
        "bookings_available": 1,
        "links": [
            {
                "rel":"rename",
                "href": "/user/69/rename",
                "method":"PUT"
            },
            {
                "rel":"change_address",
                "href": "/user/69/address",
                "method": "PUT"
            },
            {
                "rel":"reset_bookings",
                "href": "/user/69/reset_bookings/",
                "method": "PUT"
            },
            {
                "rel":"book",
                "href": "/user/69/book",
                "method": "GET"
            }
        ]
    }
}

These links are added dynamically. For example when we call 'book' for this user, the bookings_available will drop to zero and now the 'book' link will be missing when we query the user endpoind once again:

Follow-up links after booking
{
    "user": {
        "name": "Ben Dover",
        "address": {
            "street": "Square st. 25",
            "city": "Godham",
            "country": "Paradiseland"
        },
        "bookings_available": 0,
        "links": [
            {
                "rel":"rename",
                "href": "/user/69/rename",
                "method":"PUT"
            },
            {
                "rel":"change_address",
                "href": "/user/69/address",
                "method": "PUT"
            },
            {
                "rel":"reset_bookings",
                "href": "/user/69/reset_bookings/",
                "method": "PUT"
            }
        ]
    }
}

Original Examples⌗

Response containing follow-up links
{
    "user": {
        "name": "Ben Dover",
        "address": {
            "street": "Square st. 25",
            "city": "Godham",
            "country": "Paradiseland"
        },
        "bookings_available": 1,
        "links": {
            "rename": "/user/69/rename",
            "change_address": "/user/69/address",
            "reset_bookings": "/user/69/reset_bookings/",
            "book": "/user/69/book"
        }
    }
}
Follow-up links after booking
{
    "user": {
        "name": "Ben Dover",
        "address": {
            "street": "Square st. 25",
            "city": "Godham",
            "country": "Paradiseland"
        },
        "bookings_available": 0,
        "links": {
            "rename": "/user/69/rename",
            "change_address": "/user/69/address",
            "reset_bookings": "/user/69/reset_bookings/"
        }
    }
}

Links⌗