Une API REST est une interface qui permet d’établir une communication, qui respecte les contraintes d’architecture REST. L’architecture REST (Representational State Transfer) a été créée par l’informaticien Roy Fielding. C’est le type d’API le plus utilisé sur le web. 

Pour accéder à une ressource, le client envoie une requête HTTP, en retour le serveur génère une réponse avec des données encodées.  

6 contraintes ont été proposées par Roy Fielding : 

• La séparation des responsabilités entre le client et le serveur 
• L’absence d’état de session (stateless), ni le client ni le serveur n’a besoin de l’état de l’autre pour communiquer
• La possibilité de mettre les ressources en cache à tous les niveaux 
• Une interface uniforme, communication uniforme avec ressources identifiables. En vocabulaire http, il doit y avoir une URL, une réponse contenant un body et une entête
• Permettre le rajout de couches intermédiaire (Proxy, firewall, CDN etc…) 
• Facultative – Code sur demande, demander au serveur un morceau de code qui sera exécuté par le client

Les bonnes pratiques  

Utilisez des noms à la place des verbes  

N’utilisez pas :  

/getAllCats  

Utilisez plutôt : 

GET /cats  

Utilisez des noms pluriels  

/cats à la place de /cat 

/owners à la place de /owner 

Utilisez correctement les méthodes HTTP, Utilisez PUT, POST et DELETE à la place de GET pour modifier l’état. 

• Utilisez des sous-ressources pour les relations.  

GET /owners/42/cats/ → retourne la liste des chats pour le propriétaire #42 

GET /owners/42/cats/4 → retourne le chat #4 pour le propriétaire #42 

POST /owners/42/cats → Ajoute un nouveau chat pour le propriétaire #42  

PUT /owners/42/cats/4 → Modifie les données du chat #4 pour le propriétaire #42 

• Utilisez les filtres, le tri et la sélection de champ pour les collections.  

GET /owners?cats<=2 → retourne la liste des propriétaires qui possèdent plus de 2 chats. 

• Indiquez les différentes versions, la plupart du temps on utilise la lettre “v” dans l’url pour indiquer la version.  

/cats/api/v1  

Gérez les erreurs avec les codes d’état HTTP 

→ Les standards HTTP fournissent plus de 70 statuts pour décrire les données retournées. Vous n’avez pas besoin de toutes les utiliser, mais au moins 10 d’entre elles sont importantes. 

200 – OK – Tout marche correctement  

201 – OK – Une nouvelle ressource a été créée

204 – OK – La ressource a bien été supprimée

304 – Non modifié – Le client peut utiliser la donnée en cache  

400 – Mauvaise demande – La demande est invalide. L’erreur exacte devrait être expliquée dans la charge utile d’erreur 

401 – Non autorisé – La requête a besoin de l’authentification 

403 – Interdit – Le serveur a compris la demande mais l’utilisateur n’est pas autorisé  

404 – Non trouvé – Il n’y a pas de ressources derrière l’URI  

500 – Erreur serveur – Les développeurs d’API devraient éviter cette erreur 

503 – Service indisponible – Indique que quelque chose d’inattendu est arrivé côté serveur  

Acceptez et répondez avec du JSON  

La plupart des API REST utilisent le format JSON (Javascript Object Notation). Mais ce n’est pas forcément suffisant de retourner uniquement du JSON, il faut aussi spécifier le content-type dans le header. Pour cela, il faut indiquer : application/json 

Documentation d’une API REST 

Le but d’une API est d’être utilisée par de nombreux développeurs, et parfois même est destinée à des utilisateurs qui ne sont pas développeurs. Une documentation doit être accessible et facilement exploitable. 

Une documentation devrait comporter au minimum :  

• La manière de s’authentifier, si il s’agit d’une API privée 
• La définition des endpoints 
• Les paramètres éventuels  
• Des exemples de requêtes et de réponses  

Il existe plusieurs services pour documenter les API, parmi ceux-ci, en voici 3 :  

• RAML : un language basé sur YAML 
• Swagger : du JSON ou du YAML 
• Apiary : markdown (API blueprint) 

Voici des exemples d’API bien documentées et facilement exploitables :  

• L’API de Wikipedia  
• L’API de Github 

Fun facts 

Pour conclure cet article, j’ai sélectionné pour vous deux points surprenants sur les API REST.  

• Une API a été créée pour retourner tous les codes d’erreurs avec des photos de chats, elle s’appelle HTTP Cats et a le mérite d’exister pour faire rire vos collègues entre deux pauses café. Bon, comme tout le monde n’est pas très branché chat et pour ne pas faire de jaloux, il existe la même chose pour les chiens. 

• Parce qu’un fun fact ne reste jamais seul, en voici un deuxième. Dans les réponses HTTP, il existe un code insolite : 418 – I’m a teapot, qui informe que le serveur refuse de préparer le café, il s’agit d’un poisson d’avril datant de 1998.

Maintenant que vous savez ce qu’est une API REST, découvrez comment sécuriser cette dernière !