LA THORIE REST, RESTFUL ET

HATEOAS
YoruNoHikage
07 avril 2016

Table des matires

1 Introduction

2 Les contraintes

3 Les contraintes

4 Le modle de maturit de Richardson

11

5 Un exemple dAPI : prendre un rendez-vous chez le mdecin

13

6 Niveau 0

15

7 Niveau 1 : Les ressources, diviser pour mieux rgner !

17

8 Niveau 2 : Les verbes HTTP et les codes de retour

19

9 Niveau 3 : Les liens hypermdia (HATEOAS)

21

9.1 Un exemple concret

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

21

10Mmo des codes et rponses HTTP

23

11Conclusion

25

1 Introduction
*[REST] : Representational State Transfer
REST est un style darchitecture dfini dans la thse de Roy Fielding dans les annes 2000, ce
nest donc ni un protocole ni un format. Les implmentations sont donc multiples et diffrentes.
Cependant, on retrouve souvent le principe dans les API HTTP, comme cest le cas de GitHub et
Twitter par exemple.
Lanons-nous pieds joints dans un monde merveilleux !

2 Les contraintes
[REST] : Representational State Transfer [HATEOAS] : Hypermedia As The Engine Of Application State

Lauteur dfinit un certain nombre de contraintes respecter afin de devenir REST Compliant
autrement dit comment se conformer cette architecture. On dit de REST quil est sans tat.

3 Les contraintes
1. Le serveur et le client sont indpendants. Linterface utilisateur est situ ct client (une
application mobile par exemple) et le stockage est situe ct serveur (une base de donnes).
2. Contrairement laccs web classique, aucune variable de session ou autre tat volatile ne
doit tre enregistr ct serveur. Chaque requte vers le serveur est donc indpendante.
3. Mise en cache : le serveur indique au client sil peut mettre en cache les donnes quil reoit.
Cela permet dviter des requtes inutiles et ainsi prserver la bande passante.
4. Une interface uniforme.
1. On accde chaque ressource de faon unique. Il ny a quune seule faon dy accder.
2. Les ressources sont manipules via des reprsentations dfinies, elles sont accompagnes de donnes permettant sa comprhension (vous comprendrez mieux dans
lexemple).
3. Auto-description. Lencodage, par exemple, est prcis de faon claire ainsi le client
peut comprendre le document et appeler le service correspondant cet encodage.
4. Hypermdia comme moteur dapplication (HATEOAS) : la ressource indique comment
accder aux tats suivants (suppression, dition etc), le client peut ainsi connatre
quelles actions sont possibles sur la ressource en lobtenant
5. Hirarchie par couche : les ressources sont individuelles. On peut imaginer que nos ressources embarquent des ressources provenant de serveurs distants ou de mise en cache
par des serveurs intermdiaires.
6. (Facultatif) Excution de scripts ct client obtenus par le serveur. Cela permet de rendre
le client plus lger et plus gnrique.
[[question]] | Quest-ce que a veut dire tout a concrtement ?
Reprenons ces contraintes avec un lexemple de lAPI de Twitter et vulgarisons son utilisation :
1. Lapplication Twitter de votre tlphone correspond un client. Elle est indpendante des
serveurs de Twitter. Vous pouvez naviguer sur votre application, les requtes sont envoyes
et les rponses sont traites par le client afin dtre affiches.
2. Lorsque vous postez un tweet, toutes les informations envoyes permettent de vous identifier. Dans le cadre de Twitter, lauthentification se fait par lintermdiaire dune cl dAPI.
3. Les tweets sont gards sur lapplication jusqu ce que le cache soit vid.
4. 1. Laccs au tweet se fait via lURI : /statuses/show.json ?id=210462857140252672
2. Le tweet est encapsul dans un nuage de mta-donnes, il ny a pas que la ressource
3. La langue du tweet est prcise.
4. Twitter ne suit pas REST la lettre et nintgre pas de lien hypermedia, cest pour cela
que son API est documente. Cet exemple sera illustr dans la dernire partie de ce
tutoriel.

3 Les contraintes

5. Le fonctionnement de ce point est plus interne, on ne peut donc pas savoir mais Twitter
doit srement faire de la mise en cache et du load-balancing.
6. Aucun exemple ne me vient en tte. (Si quelquun connat une API qui fait a, je serai ravi
de la partager)

10

4 Le modle de maturit de Richardson

Dvelopp par Leonard Richardson, ce modle permet de dcouper les contraintes de REST en 3
tapes principales suivre afin de mettre en application la thorie de REST en tant que service
web. Et voici pour vous, si vous ne lavez pas dj vu quelque part, un schma trs important que
lon retrouve souvent :

Figure 4.1 Le modle de maturit de Richardson mis en image par Martin Fowler
Les principes de REST ne sont pas toujours respects mais lorsque lon compare la thorie la
pratique, il faut savoir faire quelques concessions et vous serez srement amens faire des choix
divergeant des standards.

11

5 Un exemple dAPI : prendre un

rendez-vous chez le mdecin
Jai choisi de reprendre les exemples fournis par Martin Fowler et de les adapter en JSON. Japprcie davantage ce format et les APIs lutilisent souvent bien quil ait des limites (on verra a tout
lheure).
Considrons que lon veut prendre un RDV chez le mdecin. Nous sommes le client et le secrtariat que lon appelle est le serveur.

13

6 Niveau 0
Je souhaite donc prendre un rendez-vous le 21 octobre 2015 avec le mdecin Doc. Il sagit dans
ce niveau dinterroger le serveur partir dun seul point dentre. On spcifie les actions ou les
ressources rcuprer dans lobjet que lon envoie.

POST /cabinetMedecin HTTP/1.1

Content-Type: application/json
## en-ttes HTTP
...
{
"prendreRDV": {
"date" : "2015-10-21",
"medecin_id" : "doc"
}
}
Jobtiens, par la suite, les crneaux disponibles dans la journe :

HTTP/1.1 200 OK
Content-Type: application/json
...
{
"creneaux": [
{
"debut": "14h00",
"fin": "14h50",
"medecin": { "id": "doc", "autre_propriete": "valeur" }
},
{
"debut": "16h00",
"fin": "16h50",
"medecin": { "id": "doc", "autre_propriete": "valeur" }
}
]
}
[[information]] | Je simplifie en mettant les dates/heures en chane de caractre, on ne va pas
sembter avec des dates | rallonge Maintenant que lon connat les crneaux libres, on veut
pouvoir le rserver ! On renvoie une requte au serveur avec laction effectuer et les informations
dont il a besoin.

15

6 Niveau 0

POST /cabinetMedecin HTTP/1.1

Content-Type: application/json
...
{
"demandeRDV": {
"creneau": {
"medecin_id": "doc",
"debut": "14h00",
"fin": "14h50"
},
"patient": { "id": "marty" }
}
}
Dans le cas dune russite, jobtiens cette rponse accompagne du contenu que jai envoy :

HTTP/1.1 200 OK
Content-Type: application/json
...
{
"RDV": {
"creneau": ...,
"patient": ...
}
}
Et sinon jobtiens une rponse ngative :

HTTP/1.1 200 OK
Content-Type: application/json
...
{
"RDVImpossible": {
"creneau": ...,
"patient": ...,
"erreur": "Ce crneau n'est pas disponible"
}
}
Vous commencez dj voir ce qui cloche nest-ce pas ? ~Non ? Le 200 OK pour une erreur, bizarre,
non ?~
Voyons comment slever vers la gloire de REST et ainsi amliorer notre architecture !

16

7 Niveau 1 : Les ressources, diviser

pour mieux rgner !
Plutt que dinterroger un service unique, il est plus intressant de parler de ressources ! Pour
faire simple, on va directement appeler le mdecin avec qui on veut prendre un RDV ! (cest bte
sil est trs occup mais au moins on gne pas le secrtariat :D ) La requte ne contiendra plus le
mdecin qui sadresser puisque nous lavons appel directement pour lui demander.

POST /medecins/doc HTTP/1.1

Content-Type: application/json
...
{ "prendreRDV": { "date" : "2015-10-21" } }
La rponse ne change que trs peu. Chaque ressource tant accessible, elle porte un identifiant
afin de la retrouver de faon unique (contrainte 4.1) :

{
"creneaux" : [
{
"id" : "1337",
...
},
{
"id" : "1645",
...
}
]
}
On a plus qu choisir notre crneau et le rserver directement :

POST /creneaux/1337 HTTP/1.1

...
La rponse est identique au niveau prcdent.
Ce niveau permet dapporter une certaine clart, on agit sur une ressource et non pas sur un service en prcisant chaque fois ce que lon veut.

17

8 Niveau 2 : Les verbes HTTP et les

codes de retour
Dans les deux premiers niveaux, vous avez d trouver trange lutilisation du POST. On aurait
tout aussi bien pu mettre GET, a aurait t identique (mais sachant que lon a modifi ltat du
serveur, a aurait vraiment pas t propre). On ne sest servi de la requte HTTP uniquement
pour que le serveur comprenne notre requte mais on a pas vraiment respect le protocole. Le
modle de Richardson, quant lui, dfinit une utilisation des verbes HTTP la plus proche possible
du protocole.
GET correspond une action sre, elle sera utilis pour rcuprer une ressource. En aucun cas, il
ne doit y avoir un changement dtat sur le serveur.
Si la ressource nest pas supprime ou modifie, GET renverra toujours la mme chose, on
dit quil est idempotent.
La rponse peut tre mise en cache par des lments intermdiaires (souvenez-vous de la
rgle n5 : hirarchie par couches).

GET /medecins/doc/creneaux?date=20151021&status=ouvert HTTP/1.1

...

Comme vous pouvez le constater, le corps de la requte est vide et les infos sont passs en arguments. Gnralement dans les APIs (mais pas toujours), les paramtres servent de filtres (tri,
pagination). Ici on rcupre uniquement les crneaux ouverts le 21 octobre 2015. La rponse,
quant elle, ne change en rien et elle ne changera pas tant que la ressource ne sera pas modifie
(premire rgle de GET).
Maintenant, on veut rserver le crneau. L encore, la requte ne change pas et cest bien un POST
que lon utilise.
[[information]] | Le fait dutiliser POST ou PUT afin de crer et/ou de mettre jour une ressource est sujet dbat. Mais | comme le pointe cette rponse, le standard veut que POST soit
utilis | lorsque lon envoie une nouvelle sous-ressource ne connaissant pas son URI et PUT
linverse, la | ressource tant modifie si elle existe dj ! | Pour prendre un exemple, ceci POST

/creneaux/1337 HTTP/1.1 et PUT /creneaux/1337/rdv HTTP/1.1 creront | la ressource

rdv dans les deux cas sur le crneau 1337.
| Pour prendre un exemple plus parlant, imaginons que vous deviez crer un commentaire
sur une news, vous | feriez POST /news/ma-super-news/comments par exemple, mais PUT
/news/ma-super-news/comments/12345 | fonctionnerait galement, bien quil soit plus
appropri pour ldition (on ne connat rarement | lidentifiant lavance).
La rponse renverra alors un 201 Created, les codes de retour tant prsent utiliss, accompagne de len-tte HTTP Location avec lURI vers la ressource. Il peut tre intressant aussi de

19

8 Niveau 2 : Les verbes HTTP et les codes de retour

lembarquer dans le corps de la rponse en supplment afin dviter une nouvelle requte pour
le client.
[[question]] | Mais si quelquun rserve en mme temps ? On fait quoi ?
Eh bien, on le dit tout simplement : Attention, il y a un conflit sur ce crneau, il est dj pris ! Ce
qui donne ceci dans la rponse :

HTTP/1.1 409 Conflict

Content-Type: application/json
...
{
"creneau": {
...
}
}
Si lon souhaite supprimer une ressource, il suffit denvoyer un DELETE de cette faon :

DELETE /creneaux/1337/rdv HTTP/1.1

## En-tte d'autorisation et d'identification :
# Utile pour restreindre la suppression l'auteur du RDV ou au mdecin
## Il ne faudrait pas que n'importe qui puisse supprimer votre RDV !
et la rponse pourra contenir un 200 OK (avec un corps de rponse fourni), un 202 Accepted
si laction nest pas encore effectue et quelle est attente et un 204 No Content si tout sest
droul correctement.

20

9 Niveau 3 : Les liens hypermdia

(HATEOAS)
[[question]] | HATEOAS, quest-ce que cest ?
HATEOAS, pour Hypermedia As The Engine Of Application State, est la contrainte (4.4) qui est la
plus prsente sur le web mais malheureusement pas souvent dans les APIs. Arriv ce niveau, on
reconnat videmment que le web est bien ancr sur le principe de REST, quelques exceptions
prs. Lorsque lon obtient une ressource, ou une page sur le web, il est trs important de la lier
dautres ressources via des liens. Cest aussi bte que a.
Pour prendre un exemple, lorsque vous dsirez accder un tuto sur Zeste de Savoir, vous nallez
pas directement sur le tuto, vous passez au moins par la page daccueil qui vous indique o vous
rendre pour obtenir le tuto. Et cest ce quoi servent les contrles hypermdia dans une API,
permettre la navigation entre les diffrentes ressources.
En rajoutant ces liens, si vous avez un client assez intelligent, il saura sadapter aux changements
de lAPI, ce qui en fait un atout car les APIs doivent voluer (les ressources peuvent changer de
nom et les actions sont amenes voluer).

9.1 Un exemple concret

Il existe actuellement plusieurs formats standardiss ou non qui sont utiliss pour lier des
donnes en JSON bien quil ne soit pas un format adapt. On retrouve HAL, JSON-LD ou encore
JSON :API. Tous ces formats ont leurs avantages et inconvnients. Cest vous de choisir et
peut-tre bien que vous ne voulez pas de JSON du tout. Je vous conseille daller faire un tour
sur les diffrents sites pour choisir celui que vous prfrez ou qui vous semble le plus pertinent.
Dailleurs, changeons les rponses en un langage plus appropri : xml.
Reprenons la rponse de notre premier GET et ajoutons-y des liens :

<creneaux>
<creneau>
<id>1337</id>
...
<link rel="self" href="http://api.example.com/creneaux/1337" />
<link rel="rdv" href="http://api.example.com/creneaux/1337/rdv" />
</creneau>
<creneau>
<id>1645</id>
...
<link rel="self" href="http://api.example.com/creneaux/1645" />
<link rel="rdv" href="http://api.example.com/creneaux/1645/rdv" />

21

9 Niveau 3 : Les liens hypermdia (HATEOAS)

</creneau>

<link rel="self" href="http://api.example.com/medecins/doc/creneaux?date=20151021&s

</creneaux>
Comme vous pouvez le voir, lajout de lien permet de connatre les actions possibles sur les ressources ainsi que les relations entre ressources. Imaginez que nous demandions tous les crneaux
du mdecin, y compris ceux qui sont dj rservs, le <link rel="rdv" ... > ne sera pas prsent dans ces derniers puisque laction nest pas possible. Ainsi on peut dcouvrir lAPI sur le
moment. La documentation nen deviens que moins utile.
Ce systme comporte quand mme des limites, on ne peut pas savoir quelle mthode HTTP utiliser
sur les ressources mais il sagit dune fonctionnalit qui peut tre trs utile lors du parcours de
lAPI.
[[information]] | Si vous voulez tester en live, vous pouvez vous rendre sur lAPI GitHub, vous
verrez que | vous pouvez vous dplacer de ressources en ressources sans avoir besoin daller sur
la doc
Voil qui clt le modle de maturit de Richardson. Il faut savoir rester pragmatique et faire des
choix en fonction de ses besoins. Il ny a pas forcment dintrt atteindre le niveau 3 si vous
ne comptez pas interagir avec dautres systmes de donnes intelligents.
Pour rsumer :
Le niveau 1 permet de diviser pour mieux rgner.
Le niveau 2 introduit des verbes afin de mieux grer les actions similaires.
Le niveau 3 introduit la possibilit de dcouvrir lAPI, la permettant dtre autodocumente.
[[question]] | Mais, RESTful, cest quoi en fait ?
Il sagit dun terme gnrique trs utilis pour indiquer le parfait respect de REST. Bien entendu,
beaucoup dAPIs se considrant REST ou RESTful ne le sont pas et ainsi, il a t dcid dutiliser
le terme HATEOAS pour parler dune API respectant le niveau 3 qui est un des points les plus
importants de REST.
[HATEOAS] : Hypermedia As The Engine Of Application State [URI] : Uniform Resource Identifier [HAL] :
Hypertext Application Language [JSON-LD] : JavaScript Object Notation for Linked Data

22

10 Mmo des codes et rponses HTTP

Voil un petit mmo des diffrents codes HTTP utiles pour les API. Je rajouterai peut-tre quelques
cas de figures qui peuvent tre intressants en pratique. Nhsitez pas menvoyer des utilisations pratiques de ces codes.
Code

Message

Signification

200

OK

Succs de rponse pour toutes mthodes sauf la cration avec

201

Created

POST.
Rponse un POST qui cre une ressource. Doit tre
obligatoirement accompagn du header Location avec le
lien vers la nouvelle ressource. On peut embarquer la
nouvelle ressource pour viter au client de refaire une
nouvelle requte.
204

No Content

Une requte russie qui ne renvoie aucun contenu (comme un

DELETE par exemple).

304

Not Modified

Utilis avec la gestion dun cache.

400

Bad Request

La requte a choue car le contenu ne peut pas tre compris

401

Unauthorized

(un contenu qui ne peut tre pars par exemple).

Lorsquune authentification a choue. Utile pour afficher
une popup quand lauthentification se fait par un navigateur.
403

Forbidden

Lauthentification est correcte mais lutilisateur ne peut pas

accder la ressource.

404
405
410

Not Found

La ressource na pas pu tre trouve.

Method Not

Quand une mthode non autorise a t utilise par

Allowed

lutilisateur.

Gone

La ressource nest plus disponible. Utile pour les vieilles

versions de lAPI.

415

Unsupported Media

Si le Content-Type est incorrect.

Type
422

Unprocessable

Utilis pour les erreurs de validation.

429

Too Many Requests

Utilis lorsque la limite de requtes autorises a t dpasse.

500

Internal Error

Un message gnrique pour indiquer quil y a eu un problme

Entity

mais quil ne vient pas de lutilisateur.

503

Service Unavailable

Le service est down ou en maintenance. Status temporaire,

en gnral.

23

11 Conclusion
Voil, maintenant que vous avez tout compris sur REST, vous allez pouvoir bien structurer votre
application ! Ce tuto ne concernait pas vraiment la mise en application au niveau code, mais il
est toujours intressant de savoir comment les choses sont faites et dcrites afin de pouvoir les
respecter par la suite.
Sources :
REST sur Wikipdia
http ://blog.xebia.fr/2010/06/25/rest-richardson-maturity-model/
http ://martinfowler.com/articles/richardsonMaturityModel.html
http ://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
REST APIs with Symfony2 : The Right Way - William Durand
Best Practices for Designing a Pragmatic RESTful API - Vinay Sahni
Merci Dominus Carnufex pour les corrections.

25