Le principe est de découper l’application sous forme de ressource que les clients peuvent utiliser au travers de requêtes HTTP.

Cette architecture destinée aux systèmes distribués a été créé en 2000 par Roy Fielding dans sa thèse de doctorat.

L’intérêt d’une API REST est de rendre les ressources de l’applications utilisables par tous les composants de celle-ci. Cela permet de mettre en place des micro-services, de la portabilité, de donner accès à certaines fonctionnalités à des personnes extérieures…

Identification d’une ressource par l’URL

L’identification de chaque ressource doit se faire via une URL qui sera décomposée logiquement. Ainsi le nom d’une ressource doit comporter le « s » du pluriel pour indiquer que sans paramètres de filtrage, on affiche tous les éléments. Lorsque l’on filtre, on laisse le pluriel, en effet, on sous-entend que l’on cherche tous les éléments puis on renvoi seulement l’élément filtré.

Par exemple :

  • http://exemple.com/books On récupère la liste de tous les livres.

  • http://exemple.com/books/5 On récupère la liste des livres puis on filtre pour récupérer celui ayant l’identifiant 5.

On peut ensuite récupérer des ressources associés grâce à la même méthode :

  • http://exemple.com/books/5/comments On récupère la liste des livres, on filtre celui ayant l’identifiant 5 puis on renvoi les commentaires lui étant associé.

  • http://exemple.com/books/5/comments/6 On récupère la liste des livres, on filtre celui ayant l’identifiant 5, on renvoi les commentaires lui étant associé et on filtre celui ayant l’identifiant 6.

Utilisation des verbes http pour identifier une opération

Pour identifier l’action à effectuer sur une ressource, les verbes http disponibles sont les suivants :

  • GET : Demande une représentation des ressources spécifiées.

  • HEAD : Même chose que GET mais ne retourne que l’entête de la réponse.

  • POST : Utilisé pour créer une ressource.

  • PUT : Utilisé pour modifier une ressource.

  • DELETE : Utilisé pour supprimer une ressource.

  • CONNECT : Etablit un tunnel vers le serveur identifié par la ressource cible.

  • OPTIONS : Utilisé pour décrire les options de communication vers une ressource visée.

  • TRACE : Réalise un chemin aller/retour en suivant le chemin de la ressource visée.

  • PATCH : Utilisé pour appliquer des modifications partielles à une ressource.

Par exemple pour créer un CRUD sur des livres :

  • Créer : POST http://exemple.com/books

  • Afficher : GET http://exemple.com/books/4

  • Mettre à jour : PUT http://exemple.com/books/4

  • Supprimer : DELETE http://exemple.com/books/4

La réponse représente la ressource

La réponse doit être compréhensible par tous les langages facilement dans le but qu’ils puissent reconstruire l’objet à l’arrivée. Le processus qui rend cela possible est la sérialisation et la déspécialisation des objets. Ainsi, les contenus peuvent être des objets, des tableaux et même des variables plus simples comme des booléens, des nombres, des chaines de caractère ou une valeur nulle.

Les formats de données les plus courants sont :

  • JSON (JavaScript Object Notation)

  • XML (Extensive Markup Language)

  • YAML (Yet Another Markup Language)

  • CSV (comma-separated values)

  • INI

Exemple de représentation d’un objet en JSON :

{
    "name":"John",
    "age":30,
    "car":"Fiat"
}

Authentification pour accéder à une ressource

La limitation de l’accès à certaines ressources est essentielle dans une architecture d’API REST. L’une des problématiques est le fait que ce type d’architecture doit être basé sur des serveurs sans état, c’est-à-dire qu’il ne faut par exemple pas stocker les sessions sur les serveurs pour permettre au service d’être scalé facilement.

  • Token de session stockée en base de données partagée

  • Clé API

  • JWT

  • OAuth 2

Utilisation de l’URL pour donner plus de pouvoir sur la donnée

Les paramètres passés en URL peuvent être utile pour effectuer un traitement supplémentaire sur l’information, cette technique est le plus souvent utilisée sur les requêtes http GET. Par exemple, nous pouvons ajouter un élément « tri » qui permettra d’effectuer un ORDER BY sur les résultats. Nous pouvons aussi ajouter un système de page pour fragmenter les résultats si la ressource s’avère trop volumineuse.

http://exemple.com/books?filter=policier&tri=asc

http://exemple.com/books?filter=policier&tri=asc&page=4&elementPerPage=25

Plus d’infos

Traduction du chapitre 5 de la thèse de Roy Fielding :

http://opikanoba.org/tr/fielding/rest/



http://www.croes.org/gerald/blog/qu-est-ce-que-rest/447/

https://fr.wikipedia.org/wiki/Representational_state_transfer

https://developer.mozilla.org/fr/docs/HTTP/M%C3%A9thode