REST

FondamentalLes 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.

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.