Guide de conception d'API HTTP chez Heroku

Wesley Beary, membre de l'équipe d'API chez Heroku, a recensé une liste de directives pour la création d'APIs HTTP+JSON, présentées sous forme condensée ici même.

Le guide démarre avec un certain nombre de recommandations générales :

• Exiger l'utilisation de TLS pour tous les appels d'API. Répondre avec 403 Forbidden pour ceux qui ne le sont pas.
• Toujours versionner une API. Utiliser l'en-tête Accept pour spécifier la version. Exiger des clients pour spécifier la version de l'API au lieu de se reposer sur celle par défaut.
• Utiliser l'en-tête ETag pour supporter le cachage des ressources.
• Identifier chaque réponse avec X-Request-ID ; utile à des fins de trace ou de débogage.
• Utiliser Range, Content-Range, Next-Range pour traiter les réponses de taille importante.

Pour passer des requêtes, le guide mentionne :

• Retourner les codes statut appropriés, comme :

  200 : GET or DELETE synchrone, PATCH 201 : POSTsynchrone ... 401 : Appel non autorisé 429 : Trop de requêtes etc.

• Retourner les ressources complètes lorsqu'elles sont disponibles.

• Accepter le JSON sérialisé dans les requêtes de manière symétrique aux réponses JSON.
• Utiliser des formats de chemin consistants. Les noms de ressource doivent utiliser la forme plurielle, sauf s'ils se réfèrent à des singletons.
• Utiliser les minuscules pour les chemins et les attributs pour être cohérent avec les noms de domaine.
• Permettre de spécifier par leur nom en plus de leur UUID certaines ressources, comme les noms d'application.
• Tenter de limiter la profondeur d'imbrication des ressources en les allouant au plus près de la racine.

En ce qui concerne les réponses, Beary suggère :

• Utiliser des IDs globalement uniques pour chaque ressource.
• Fournir un horodatage standard pour les ressources.
• Pour les horodatages, utiliser l'UTC au format ISO8601.
• Imbriquer les relations de clé étrangère pour pouvoir inclure plus de détails liés à une ressource sans modifier la structure de la réponse.
• Fournir des erreurs détaillées, comprenant une ID exploitable par des systèmes informatiques, un message d'erreur à destination des humains et une URL optionelle qui pointe sur des détails supplémentaires.
• Etablir un seuil limite de requêtes et informer le client sur le nombre de jetons de requête disponible à chaque réponse, en utilisant une en-tête du type RateLimit-Remaining.
• Le JSON doit être minifié dans toutes les réponses.

Le guide comprend plus de conseils :

• Fournir le schéma JSON dans un format exploitable par des systèmes informatiques.
• Inclure une documentation d'APIs détaillée pour les développeurs.
• Permettre aux développeurs de tester les APIs.
• Les APIs doivent être identifiées en fonction de leur statut d'exploitabilité : prototype/dévelopement/production.

Nous avons demandé à Beary comment ils sont parvenus à ces directives et d'en expliquer certaines.

InfoQ : Avez-vous eu un guide depuis le départ ?

WB : J'ai eu certaines parties du guide depuis longtemps, mais elles étaient plutôt brutes de décoffrage et n'existaient que dans ma tête. A partir de mon travail sur github.com/fog/fog et des trucs associés, j'ai consommé beaucoup d'APIs différentes, ce qui a beaucoup contribué à forger mon opinion.

InfoQ : Si vous n'aviez pas ce guide depuis le départ, comment avez-vous développer l'API ? De manière itérative ?

WB : Sans guide plus formel, cela a été un vrai processus itératif. Malheureusement, en plus d'être plutôt lent, le processus itératif n'était pas scalable. Il a fait de moi un obstacle à l'ajout de nouvelles choses. Nous avons construit le guide pour aider à la distribution du processus de décision. Nous continuons à itérer, mais souvent c'est également sur le guide lui-même. Il y a plusieurs discussions en cours (github.com/interagent/http-api-design/issues), ce qui contribue à clarifier et faire évoluer le document tandis que nous apprenons plus et que d'autres développeurs l'adoptent.

InfoQ : Pourquoi est-ce recommandé de retourner la ressource complète dans le cas d'une opération PUT ou DELETE ?

WB : Les cas d'exception sont l'ennemi des interfaces et des directives. Souvent, la ressource sera demandée et la laisser de côté est juste une optimisation. Je pense que l'avoir comme comportement optionnel pourrait avoir du bon sens dans de nombreuses situations, mais il est important de disposer d'un défaut simple et utilisable. Ceci étant dit, c'est un sujet polémique et il y a une sérieuse discussion en cours à propos du pour et du contre à https://github.com/interagent/http-api-design/issues/9.

InfoQ : Pourquoi utiliser uniquement des temps UTC formatés en ISO8601 ?

WB : De même que le retour de la ressource complète, le fait d'avoir une règle consistante (sans exception) rend plus facile le raisonnement à propos de ce que l'on fait et réduit le nombre de décisions que vous devez prendre lorsque vous concevez quelque chose. De plus, les fuseaux horaires sont déments et terribles. J'ai perdu le compte du nombre d'erreurs relatives aux fuseaux horaires que j'ai rencontrées et causées. Dans l'espoir de réduire les problèmes, nous choisissons de toujours utiliser un format et un fuseau connu.