REST
Fondamental : Les 5 règles :
Les 5 règles :
Règle n°1 : l'URI comme identifiant des ressources
Règle n°2 : les verbes HTTP comme identifiant des opérations
Règle n°3 : les réponses HTTP comme représentation des ressources
Règle n°4 : les liens comme relation entre ressources
Règle n°5 : un paramètre comme jeton d'authentification
Règle n°1 : l'URI comme identifiant des ressources
Complément :
Règle n°1 : l'URI comme identifiant des ressources
REST se base sur les URI (Uniform Resource Identifier) afin d'identifier une ressource.
Ainsi une application se doit de construire ses URI (et donc ses URL) de manière précise, en tenant compte des contraintes REST.
Il est nécessaire de prendre en compte la hiérarchie des ressources et la sémantique des URL pour les éditer.
Exemples de URI erroné :
http://monsiteweb.com/robot
Correction :
http://monsiteweb.com/robots
Dans une API REST typique, une ressource aura deux patterns d'URL.
Le premier est le pluriel de la ressource, par exemple /robots .
Le deuxième est constitué de ce pluriel, suivi de l'identifiant unique correspondant à une ressource particulière, par exemple /robots/<id_robot> , dans lequel <id_robot> est l'identifiant unique de ce robot.
Ces deux patterns forment le premier endpoint (point final) supporté par notre API.
On l'appelle API endpoint parce qu'il se situe à la fin de l'URL, comme dans http://monsiteweb.com/<endpoint_est_ici>.
Pour faciliter les recherches dans une API, les URL sont complétées par des chaînes d'interrogation (query string).
Ce sont de petits textes qui se situent à la fin d'une URL pour faire passer quelque chose à l'API.
Par exemple ici, tout ce qui est après le point d'interrogation est une chaîne d'interrogation :
http://monsiteweb.com/capteurs?key=value
Pour trier les capteurs de type "analogique" :
http://monsiteweb.com/capteurs?type=analogique
On peut inclure plusieurs paramètres dans la recherche, les uns après les autres, séparés par une esperluette (&),
par exemple :
http://monsiteweb.com/capteurs?type=analogique&alimentation=5V
Règle n°2 : les verbes HTTP comme identifiant des opérations
Complément :
Règle n°2 : les verbes HTTP comme identifiant des opérations
La seconde règle d'une architecture REST est d'utiliser les verbes HTTP existants plutôt que d'inclure l'opération dans l'URI de la ressource.
Ainsi, généralement pour une ressource, il y a 4 opérations possibles (CRUD) :
Créer (create)
Afficher (read)
Mettre à jour (update)
Supprimer (delete)
HTTP propose les verbes correspondant :
Créer (create) => POST
Afficher (read) => GET
Mettre à jour (update) => PUT
Supprimer (delete) => DELETE
Créer une ressource capteur :
POST http://monsiteweb.com/capteurs
Afficher un capteur en particulier :
GET http://monsiteweb.com/capteurs/accelerometre
Mettre à jour :
PUT http://monsiteweb.com/capteurs/accelerometre
Supprimer :
DELETE http://monsiteweb.com/capteurs/accelerometre
Règle n°3 : les réponses HTTP comme représentation des ressources
Complément :
Règle n°3 : les réponses HTTP comme représentation des ressources
Il est important d'avoir à l'esprit que la réponse envoyée n'est pas une ressource, c'est la représentation d'une ressource.
Ainsi, une ressource peut avoir plusieurs représentations dans des formats divers : HTML, XML, CSV, JSON, etc.
C'est au client de définir quel format de réponse il souhaite recevoir via l'entête Accept.
Il est possible de définir plusieurs formats.
Réponse en HTML :
GET /robots
Host: monsiteweb.com
Accept: text/html
Réponse en JSON :
GET /robots
Host: monsiteweb.com
Accept: application/json
Règle n°4 : les liens comme relation entre ressources
Complément :
Règle n°4 : les liens comme relation entre ressources
Les liens d'une ressource vers une autre ont tous une chose en commun : ils indiquent la présence d'une relation.
Il est cependant possible de la décrire afin d'améliorer la compréhension du système.
Pour expliciter cette description et indiquer la nature de la relation, l'attribut rel doit être spécifier sur tous les liens.
Ainsi l'IANA donne une liste de relation parmi lesquelles :
contents
edit
next
last
payment
etc.
La liste complète sur le site de l'IANA : http://www.iana.org/assignments/link-relations/link-relations.xml
Règle n°5 : un paramètre comme jeton d'authentification
Complément :
Règle n°5 : un paramètre comme jeton d'authentification
Comment authentifier une requête ?
La méthode est très simple et très utilisée par des APIs renommées (Google, Yahoo, etc.) : le jeton d'authentification.
Chaque requête est envoyée avec un jeton (token) passé en paramètre $_GET de la requête.
Ce jeton temporaire est obtenu en envoyant une première requête d'authentification puis en le combinant avec nos requêtes.