HATEOAS Expliqué en 5 minutes

Pour comprendre HATEOAS, il faut connaître le principe des API REST.

Dans ces API, une ressource est représentée côté client dans un format donné.
Cette représentation varie en fonction de son état. Ainsi, GET /user/c7daf25d
peut retourner un statut 404 Not Found à un instant donné, puis 200 OK à un
autre (lorsque la ressource aura été créée).

Cependant, le statut HTTP n’est pas la représentation : la représentation, c'est
le contenu de la réponse.

Par exemple, un "utilisateur" peut être représenté par une structure JSON simple
indiquant son état :

{
    "username": "sample",
    "status": "Invited"
}

Puis évoluer :

{
    "username": "sample",
    "status": "Registered"
}

Cette pratique pose un problème : c’est au client de savoir quelles actions sont possibles sur la ressource.

Les règles peuvent être variées et complexes. Elles peuvent dépendre de l’état
("Je peux enregistrer un utilisateur qui a été invité"), mais aussi d’autres
paramètres implicites, comme les droits d’accès ("Je peux inviter un utilisateur
si j’ai le rôle d’administrateur"). Ces règles peuvent également se combiner.

Dans ce modèle, les règles doivent être connues à la fois par le service qui expose
l’API et par les clients qui l’utilisent. À chaque nouvelle règle, il faut
synchroniser toutes les parties, ce qui devient rapidement difficile lorsque
plusieurs clients consomment le même service.

C’est là que HATEOAS prend tout son intérêt. La représentation d’une ressource peut
inclure non seulement son état, mais aussi les transitions possibles :

{
    "username": "sample",
    "status": "Invited",
    "transitions": [
        {
            "name": "register",
            "action": "/user/c7daf25d/registration"
        }
    ]
}

Avec ces "transitions", les clients n’ont plus besoin de connaître les règles
métier en amont. Ils peuvent suivre les liens fournis pour adapter leur
comportement ou leur interface.

Le service, en revanche, doit centraliser cette logique : il détermine quelles
relations exposer en fonction du contexte (état, droits, etc.) et construit la
représentation en conséquence.

Cela introduit un coût supplémentaire côté serveur, mais permet de simplifier fortement les clients et de les recentrer sur leur propre logique métier.

En pratique, il existe plusieurs formats standardisés pour représenter ces
relations. Ici, l’exemple reste volontairement générique. Si vous mettez en place
HATEOAS, il est recommandé d’adopter un format existant, car il couvre déjà de
nombreuses problématiques.

Enfin, certains frameworks proposent un support natif de HATEOAS. Dans les autres cas, il faudra définir une approche adaptée pour l’implémenter proprement.