markdown guide

Premise: HATEOAS is the actual "magic" in REST. Technically if you don't do HATEOAS you're not REST, you're just a HTTP API (DEV's v0 API is such, I'd like make it smarter in the future :D).

The Richardson Maturity Model should help: martinfowler.com/articles/richards...

Explained to a five year old: you know how web pages have link that allow you to navigate from one page to another right? HATEOAS is the same thing for a machine: how does a machine know how to jump from one thing to another? With links. HATEOAS is just that.


I have seen public APIs with link to next pages inside Header / and some other public APIs inside JSON response.

However, for internal APIs, even when there are separated frontend team and backend teams; do we really need to go that far? How is it practical / convenient?


Designing APIs well is hard, no matter if you use REST, GraphQL or anything else.

A good question you should ask yourself is how your clients are going to consume the API, or how would you like them to. Once you have a good knowledge of the pros and cons of the various approaches and have a talk with your team you'll probably know if you need one, or the other, or both.

An approach I'd like to try someday is "Design-fist API" in which you start writing the specs before you start and then you have a bunch of tools to mostly generate the API for you. It sounds a bit like UML but it's a bit better.

There are A LOT of concepts around designing APIs. I think already reaching level 2 of the maturity model with a clean "RESTish" API is a decent goal to start. You can still add HATEAOS on top of it.

Or you can choose GraphQL and go an a different route :D


If the GraphQL endpoint only receives queries by GET verb and mutations by POST verb I'd say it is also RESTful. 🤷‍♂️

The principle behind RESTful, namely stateless protocol driving stateful application, is seen in places like Clojure, Flux.


Yufan, not really, as one of the principles of REST is the representation of resources by addressable URIs. GraphQL uses /graphql (or whatever it has been decided) for everything. It's more similar to SOAP in that regard.

See martinfowler.com/articles/richards...