How useful/important is REST HATEOAS ( maturity level 3)?

Question

I\'m getting involved in a project where some senior team members believe that a REST API has to be HATEOAS compliant and implement all Richardson\'s maturity levels (http:/

Answer 1

We are building a REST level 3 API where our response is in HAL-Json. HATEOAS is great for both front and back-end but it comes with challenges. We made some customizations/additions for also managing ACL inside the HAL-Json response (which doesn't break the HAL-Json standard).

The biggest advantages to HATEOAS I see is that we do not need to write/guess any urls on our front-end application. All you need is a entry point (https://hostname) and from there on you can just browse your way through the resources using the links or templated links provided inside the response. Like that versioning can be handled easily, renaming/replacing urls, extending resources with additional relations without breaking front-end code.

Caching of resources on front-end is a piece of cake using the self links. We also push resources to clients through a socket connection, since those are also rendered in HAL we could easily add them to cache the same way.

Another advantage of using HAL-Json is that it is clear what the response model should look like, since there is a documented standard that should be followed.

One of our customizations is that we added an actions object inside the self-link object that exposes to the front end which actions or CRUD operations the authenticated user is allowed to perform on the respective resource (create:POST, read:GET, update:PUT, edit:PATCH, delete:DELETE). Like this our front end ACL is totally dictated by our REST API response, moving this responsibility fully to the the back-end model.

So to give a quick example you could have a post object in HAL-Json that looks something like this:

{
    "_links": {
        "self": {
            "href": "https://hostname/api/v1/posts/1",
            "actions": {
                "read": "GET",
                "update": "PUT",
                "delete": "DELETE"
            }
        }
    },
    "_embedded": {
        "owner": {
            "id": 1,
            "name": "John Doe",
            "email": "john.doe@example.com",
            "_links": {
                "self": {
                    "href": "https://hostname/api/v1/users/1",
                    "actions": {
                        "read": "GET"
                    }
                }
            }
        }
    },
    "subject": "Post subject",
    "body": "Post message body"
}

Now all we have to do on front end is build a AclService with an isAllowed method that checks whether the action we want to perform is in the actions object.

Currently on front-end it looks as simple as: post.isAllowed('delete');

I think REST level 3 is great, but it can lead to some headaches. You will need to have a great understanding of REST and if you want to work with level 3 REST I would suggest to follow the REST concept strictly otherwise you will easily get lost on your way when implementing it.

In our case we have the advantage that we are building both front and back-end but in principle it should NOT make a difference. But a common pitfall I have seen in our team is that some developers try to solve front-end issues (architecture) by changing their back-end model so it "suits" the front-end needs.