Comment rédiger un aperçu d'API que les développeurs peuvent utiliser
Bêta privée. L'accès se fait par liste d'attente, et les offres payantes ouvrent à la fin de la bêta. Rejoignez la liste d'attente.
Un aperçu d'API est la première page qu'un développeur lit, et souvent la seule avant de décider de s'intégrer ou non. Il doit répondre rapidement à quelques questions, et toujours au même endroit, avec les mêmes titres.
Ce qu'il faut inclure, dans l'ordre
- Résumé. Ce que fait l'API, à qui elle s'adresse et un cas d'usage typique, en deux ou trois phrases.
- URL de base. Une ligne avec la version dans le chemin, ainsi que l'URL du bac à sable s'il en existe un.
- Authentification. Comment obtenir une clé, quel en-tête la transporte et si les clés diffèrent selon l'environnement.
- Points d'accès. Un tableau avec la méthode, le chemin, une description d'une ligne et l'indication de la pagination et de l'idempotence de chaque point d'accès. Les détails des paramètres peuvent figurer dans la référence.
- Limites de débit. La limite sous forme de nombre, les en-têtes qui l'indiquent et ce que doit faire un client lorsqu'elle est dépassée.
- Gestion des versions. Ce qui constitue un changement incompatible et le nombre de jours de préavis accordés avant le retrait d'une version.
- Erreurs. Un tableau des codes de statut, des codes d'erreur, de leur signification et de l'indication de savoir si chacun peut être réessayé sans risque.
Les erreurs qui font perdre du temps aux développeurs
- Placer l'authentification sur une autre page, si bien que le premier appel est bloqué par un lien que le lecteur doit trouver.
- Lister des points d'accès sans dire lesquels sont paginés ou quelles écritures sont idempotentes, si bien qu'une relance peut créer un doublon.
- Ne documenter que le cas nominal, sans tableau d'erreurs, si bien que chaque client invente sa propre gestion.
- Donner des limites de débit comme "raisonnable" ou "usage équitable", au lieu d'un nombre et d'un nom d'en-tête.
- Ne rien dire de la dépréciation, si bien qu'une version retirée casse sans prévenir.
- Laisser la mise en page dériver d'une API à l'autre, si bien que les développeurs doivent réapprendre la page à chaque fois qu'ils ouvrent un nouvel aperçu.
Exemple concret : Parcel Tracking API
Il s'agit d'un exemple fictif. La Parcel Tracking API, ses clés, ses identifiants, ses limites et ses codes d'erreur sont tous inventés, mais ils sont cohérents entre eux, si bien que vous pouvez vérifier chaque section par rapport aux autres.
Résumé. La Parcel Tracking API permet à un marchand de créer une expédition, de lire son statut actuel et de lister les événements de suivi de chaque colis. Elle s'adresse aux développeurs qui relient une boutique en ligne ou un système d'entrepôt aux étiquettes d'expédition et aux mises à jour de livraison.
URL de base. https://api.parceltrack.example/v2 pour la production. Le bac à sable est https://sandbox.parceltrack.example/v2 et n'accepte que les clés de test.
Authentification. Envoyez votre clé d'API comme jeton Bearer dans l'en-tête Authorization : Authorization: Bearer pt_live_.... Les clés commençant par pt_live_ ne fonctionnent que sur l'URL de base de production, et les clés commençant par pt_test_ ne fonctionnent que sur le bac à sable. Créez vos clés dans Paramètres, puis Clés d'API. Une clé révoquée renvoie 401 lors de sa prochaine requête.
Points d'accès. Chaque chemin ci-dessous est relatif à l'URL de base.
| Méthode | Chemin | Description | Paginé | Idempotent |
|---|---|---|---|---|
| POST | /shipments | Créer une expédition et recevoir son numéro de suivi. | non | seulement avec un en-tête Idempotency-Key |
| GET | /shipments/{id} | Lire une expédition et son statut actuel. | non | oui |
| GET | /shipments | Lister les expéditions de votre compte, les plus récentes en premier. | oui | oui |
| GET | /shipments/{id}/events | Lister les événements de suivi d'une expédition, les plus récents en premier. | oui | oui |
| POST | /shipments/{id}/cancel | Annuler une expédition qui n'a pas encore été collectée. | non | non |
POST /shipments n'est idempotent que si vous envoyez un en-tête Idempotency-Key. L'API conserve cette clé pendant 24 heures, et une relance avec la même clé renvoie l'expédition d'origine au lieu d'en créer une seconde. Les points d'accès paginés acceptent limit (de 1 à 100, 25 par défaut) et cursor, et renvoient next_cursor, qui vaut null sur la dernière page. Annuler une expédition deux fois renvoie 409, vérifiez donc le statut avant de relancer une annulation.
Limites de débit. La production autorise 300 requêtes par minute et par clé d'API. Le bac à sable en autorise 60 par minute et par clé. Chaque réponse contient trois en-têtes : RateLimit-Limit (le quota de la fenêtre), RateLimit-Remaining (les requêtes restantes dans la fenêtre en cours) et RateLimit-Reset (le nombre de secondes avant la réinitialisation de la fenêtre). Les requêtes rejetées comptent dans la limite.
Lorsqu'une clé dépasse son quota, l'API renvoie 429 avec un en-tête Retry-After indiquant le nombre de secondes à attendre. Attendez au moins ce délai, puis relancez. Si les requêtes continuent de renvoyer 429, espacez les tentatives de manière exponentielle à partir d'une seconde : doublez l'attente à chaque tentative, ajoutez une gigue aléatoire et arrêtez après 5 tentatives. Ne relancez pas en boucle serrée.
Gestion des versions et dépréciation. La version actuelle est la v2, qui figure dans le chemin de l'URL de base. Un changement incompatible est une modification qui peut faire échouer un client qui fonctionne : suppression ou renommage d'un champ, changement de type d'un champ, changement de sens d'un code d'erreur, ou obligation de rendre un paramètre optionnel. L'ajout de points d'accès, de paramètres optionnels et de champs de réponse n'est pas incompatible, donc les clients doivent ignorer les champs de réponse qu'ils ne reconnaissent pas. Une version dépréciée renvoie un en-tête Deprecation et un en-tête Sunset indiquant la date de retrait. Le préavis est d'au moins 180 jours avant la date Sunset, et le titulaire du compte reçoit un e-mail au début du préavis.
Erreurs. Chaque erreur renvoie un corps JSON contenant un champ error avec un code du tableau ci-dessous, et un champ message destiné aux journaux. Analysez le code, pas le texte du message.
| Statut | Code d'erreur | Signification | Relance sans risque |
|---|---|---|---|
| 400 | invalid_request | Un champ est absent ou a un format incorrect. Le corps liste chaque problème dans details. | non |
| 401 | unauthorized | La clé est absente, révoquée ou destinée à l'autre environnement. | non |
| 404 | shipment_not_found | Aucune expédition portant cet identifiant n'existe dans votre compte. | non |
| 409 | shipment_state_conflict | L'action ne correspond pas à l'état de l'expédition, par exemple annuler une expédition déjà collectée. | non |
| 429 | rate_limited | La clé a utilisé son quota pour la minute en cours. | oui, après le délai Retry-After |
| 503 | service_unavailable | Panne temporaire. Relancez avec une temporisation croissante, et réutilisez le même Idempotency-Key sur les requêtes POST. | oui, avec une temporisation croissante |
Phrases faibles et phrases solides
Trois phrases typiques tirées d'aperçus, chacune suivie d'une réécriture plus forte du même point.
Faible : "L'authentification utilise des jetons."
Solide : "Envoyez votre clé d'API dans l'en-tête Authorization sous la forme Bearer suivi de la clé. Les clés commençant par pt_test_ ne fonctionnent que sur le bac à sable, et les clés commençant par pt_live_ ne fonctionnent que sur la production."
Faible : "Les limites de débit s'appliquent à tous les points d'accès."
Solide : "Chaque clé peut envoyer 300 requêtes par minute vers la production et 60 vers le bac à sable. Lisez RateLimit-Remaining dans chaque réponse. Lorsque vous recevez un 429, attendez le nombre de secondes indiqué dans Retry-After avant la requête suivante."
Faible : "Les listes sont paginées."
Solide : "Les points d'accès de liste renvoient 25 éléments par défaut, et jusqu'à 100 lorsque vous passez limit. Passez la valeur next_cursor de chaque réponse comme cursor pour obtenir la page suivante. Lorsque next_cursor vaut null, vous avez atteint la dernière page."
Liste de contrôle de relecture
Un relecteur peut parcourir ces huit questions en cinq minutes environ.
- Un développeur peut-il réussir un premier appel en s'appuyant uniquement sur cette page ?
- L'URL de base contient-elle la version, et existe-t-il une URL de bac à sable ?
- La section d'authentification nomme-t-elle l'en-tête, le format de clé et l'environnement dans lequel fonctionne chaque clé ?
- Chaque point d'accès indique-t-il s'il est paginé et s'il est idempotent ?
- Les limites de débit sont-elles données sous forme de nombres, avec les noms d'en-têtes et le comportement face au 429 ?
- La section sur les versions définit-elle un changement incompatible et précise-t-elle le délai de préavis avant le retrait ?
- Chaque ligne d'erreur indique-t-elle si une relance est sans risque, et cette réponse correspond-elle au tableau des points d'accès ?
- Les chiffres, identifiants et codes concordent-ils dans toutes les sections ?
Garder des aperçus cohérents
Si vous maintenez plusieurs API, ou si vous les rédigez pour plusieurs clients, un modèle fixe conserve le même ordre et les mêmes tableaux. Wordspecs propose un modèle d'aperçu d'API avec ces champs, et l'aperçu d'API d'exemple (un service fictif de suivi de colis) montre son apparence. Les fiches s'exportent en Markdown, PDF et Word.
À lire aussi : exporter en Markdown, PDF et Word.