Concevoir une API REST: Les points importants

Catégorie: Web (Mis à jour le 14-09-2015 11:28:56)

Aujourd'hui, de plus en plus de services sur internet proposent une API développeur pour interagir avec ce service. Cela permet de décupler les possibilités d'integration et donc la portée de votre produit.

Cet article n'a pas la prétention de couvrir tous les cas, je l'ai rédigé pour faire suite à l'excellent Build APIs you won't hate de Phil Sturgeon. Ici, je me contente de souligner des points qui me semblent importants (évoqués en détail dans le livre) mais qui ne sont (a mon avis) pas assez respectés dans la réalitée.

Pourquoi je fais une API?

C'est un point à ne jamais oublier, si on veux faire une API, c'est pour que d'autres l'utilisent. Du coup il ne faut pas non plus oublier que tout ce qu'un développeur veux, c'est pouvoir l'utiliser. Il ne veux pas avoir des centaines de pages de docs à chercher ou lire avant de comprendre comme ça marche.

Pour repecter ça, gardez a l'esprit que votre API doit être aussi simple et standard que possible. Pas de features cachés, pas d'écart par rapport au standart http.

Un exemple simple: si votre API a besoin d'une clé pour être utilisée, assurez vous qu'un nouvel arrivant peux la récuperer et trouver comment faire sa premiére requête en moins d'une minute.

C'est un point important qui guidera les points suivants.

Authentifier par token plutôt que session

Les sessions c'est bien, mais l'architecture REST doit rester stateless (sans état). Les sessions rajoutent une couche d'état à vos transactions et on se retrouve avec un systeme bancale, peu scalable.

Pour quand même gérer une authentification, il vaux mieux utiliser un système de token comme oauth ou jwt. Grâce à ce système, les données de login sont transmises par le client dans un token hashé. On dispose des informations mais on n'utilise aucun stockage coté serveur.

L'avantage, c'est que le token peux être généré sur n'importe quel ordinateur qui en posséde la clé la chiffrement. Grace à un tel systeme, vos utilisateurs pourrons génerer et controler eux-même l'authentification des clients à votre api depuis leur serveur!

Utiliser HTTP au maximum

Souvent, votre API se base sur HTTP pour la communication. Hors HTTP implémente déjà certaines choses comme les codes d'erreurs. Dans les cas d'erreur, on est souvent tenté de retourner un statut HTTP 200 (OK) et de joindre l'erreur dans le corps. C'est une mauvaise pratique car cela rend votre API moins expressive et force vos utilisateurs à consulter votre documentation pour savoir lire l'erreur.

Une bonne pratique est donc de trouver le coder HTTP le plus proche de votre erreur, puis de joindre un message détaillé dans le corps de la réponse.

C'est pour moi un point trés peu respecté mais trés important: utilisez aussi au maximum les headers HTTP pour transmettre des informations. Ceux qui on créé HTTP on pensé à tout ça bien avant vous.

Attention au GET

Le protocole HTTP décrit la méthode GET comme une consultation d'une vue sur l'information. Si il y a modification, utilisez le mot clé adapté (PUT, DELETE ou à défaut POST).

Il ne faut jamais implémenter une modification derrière une méthode GET!

Imaginez si quelqu'un décide un jour de crawler les URL GET de votre API? (histoire vécue!)

Conclusion

Pour résumer ces bonnes pratiques, je dirais que l'important est de rester standart au maximum et de garder à l'esprit que la meilleure documentation c'est celle que l'on a pas besoin de lire!

Si vous voulez en savoir plus, je vous recommande une derniére fois Build APIs you won't hate qui couvre le sujet de maniére trés exhaustive.

A lire aussi:

[PHP] [Laravel] Changer le format de date Eloquent

[Web] Voici un petit bout de code bien utile qui permet de changer le format de date retourné par défaut par les modeles Eloquent. Utile pour localiser simplement les dates de son site dynamiquement par exemple.
Suite...

Projet Pollen: Initiation à GIT

[Web] Pour le projet annuel de mon année de master 2, j'ai eu a faire une initiation a GIT pour le reste de la promo. Je partage donc cette ressource ici pour référence.
Suite...