Publié le 27 mars 2025 par Andrew Owen
(7 minutes)
On m’a récemment demandé quelles étaient mes ressources préférées et mes meilleures pratiques pour rédiger des documents clairs et structurés sur les API. J’ai développé mon propre style pour la rédaction des documents d’API, mais jusqu’à présent je ne l’ai pas publié. Bien que j’aie principalement travaillé avec des API REST, ces conseils s’appliquent également à GraphQL et à toute autre API. Mais avant d’aborder le style d’écriture, l’exigence la plus importante pour de bonnes documentations d’API est une bonne API. Si vous utilisez REST, validez-la avec Stoplight. Si les points de terminaison ne sont pas cohérents dans la manière dont ils gèrent les paramètres communs, il n’y a aucun moyen de contourner le problème. Cela semble être un problème plus important avec REST et peut expliquer l’abandon de REST au profit de GraphQL. La prochaine chose dont vous avez besoin est une documentation statique et consultable. N’attendez pas de vos utilisateurs GraphQL qu’ils trouvent les informations dont ils ont besoin en parcourant votre schéma dans Apollo. N’attendez pas de vos utilisateurs REST qu’ils fassent défiler le bas de la page de l’interface Swagger pour savoir comment formater les données pour un point de terminaison donné. Si vous avez besoin d’une solution sans budget, Redocly CLI et Magidoc sont de bons points de départ pour REST et GraphQL respectivement. À moins que vous n’utilisiez un hébergement AWS (qui n’est pas compatible avec les URL propres de Magidoc). Et ne pensez pas que vous avez terminé lorsque vous avez publié votre schéma. Les développeurs ont besoin de flux de travail, d’exemples de code et d’informations de référence pour comprendre comment ils sont censés utiliser votre API. Idéalement, ces informations devraient figurer sur un portail public destiné aux développeurs. Vos concurrents ne pourront pas cloner votre produit en examinant votre API. Et même s’ils commencent à ajouter des fonctionnalités basées sur votre API, vous aurez toujours plusieurs longueurs d’avance.
Lignes directrices générales en matière de style
Lorsque je suis devenu rédacteur d’API, j’ai constaté que, comme pour les autres logiciels, la documentation est souvent négligée. Mais si vous voulez que les gens utilisent vos API, elles doivent être bien documentées. Cependant, la rédaction d’API n’est pas la même chose que la rédaction technique traditionnelle. Utilisez un style d’écriture laconique et factuel. Les fragments de phrases sont souhaitables. Évitez les adjectifs et les adverbes. Vous devez fournir
Des informations complètes sur chaque composant de l’API
Les coordonnées des personnes à contacter au cas où les développeurs auraient des questions ou auraient besoin d’une assistance supplémentaire.
Des organigrammes montrant la séquence des méthodes les plus couramment utilisées pour les cas d’utilisation les plus courants.
Des guides de démarrage montrant comment développer un programme pour un cas d’utilisation courant.
Des informations sur les performances et les réglages
Des exemples de programmes illustrant les cas d’utilisation courants
Des extraits de code de travail pour chaque méthode, fonction et ressource. Il n’est pas nécessaire d’avoir des exemples complets, mais de montrer une utilisation courante de l’élément en question.
À moins que vous n’écriviez exclusivement pour un public interne, utilisez l’anglais américain et ne traduisez pas votre schéma d’API. Le langage doit être suffisamment simple pour qu’un développeur puisse le suivre sans avoir à le traduire.
Noms des points d’accès
minuscules (sauf initiales et acronymes)
descriptif (action-objets-critères)
le plus brièvement possible
voix active
utiliser CRUD pour l’action (create, read, update, delete)
include all match criteria (example: by user or ID)
Exemple: read API key by ID
Description des points finaux
Cas de condamnation.
descriptif (action-objets-critères)
phrases brèves
voix passive
des actions lisibles par l’homme. Exemple:
POST: Creates
GET: Retrieves
PUT: Updates
DELETE: Removes
Exemple: Retrieves details of a registered API key for the current user by ID.
for REST provide at least the minimum boilerplate text for each response
Example: 404 Not found: The URI isn’t valid, or the requested resource doesn’t exist.
REST specific guidelines
J’ai documenté les principes des API REST ailleurs. Personne ne les respecte, c’est pourquoi les API sont qualifiées de RESTful. Les méthodes HTTP doivent être utilisées de manière cohérente pour des tâches spécifiques.
Méthode
CRUD
Code de réponse typique
POST
Create
201 Created
GET
Read
200 Success
PUT
Update
202 Accepted
DELETE
Delete
204 No Content
Les autres méthodes HTTP sont les suivantes :
HEAD - Presque identique à GET, mais sans le corps de la réponse.
OPTIONS - Décrit les options de communication pour la ressource cible.
PATCH - Applique des modifications partielles à une ressource.
Je recommande d’éviter ces trois éléments dans les API publiques, bien que vous puissiez avoir des raisons de les utiliser en interne.
Texte modèle
L’une des limites de la génération actuelle d’outils de documentation Markdown et REST API est qu’ils n’offrent que peu ou pas de support pour la réutilisation automatisée du contenu. C’est pourquoi vous devez conserver une liste de définitions standard et d’exemples de charges utiles valides. Par exemple :
Adresse - Utilisez l’adresse principale de votre entreprise.
Barcode - 019000000002 (format UPC-A avec chiffre de contrôle)
Brand - Ownbrand (trop générique pour être enregistré en tant que marque)
Pays - USA (format ISO 3166-1 alpha-3)
Numéro de carte de crédit - 41111111111111 (Utilisez n’importe quel CVV, NOM et future DATE D’EXPIRATION. La valeur de l’achat doit être inférieure à 500 $. https://docs.stripe.com/testing)
Prénom - N’utilisez pas d’autres termes pour le prénom. Dans certaines cultures, le nom de famille précède le prénom.
GUID - 01234567-890a-bcde-f012-34567890abcd
Nom de famille - N’utilisez pas d’autres termes pour le nom de famille. Dans certaines cultures, le nom de famille précède le prénom.
Téléphone - +1 202 555 0199 (les numéros 555 se terminant par 0100-0199 sont fictifs)
URL - www.example.com (exemple.com est réservé à la documentation)
Codes de réponse HTTP
Vous devez fournir autant d’informations que possible sur le code de réponse. Le niveau minimum acceptable de documentation est le numéro, une brève description significative et une explication des cas d’utilisation typiques.
1xx: information
100 — Continue.
101 — Switching protocols.
102 — Processing.
103 — Early hints.
2xx: success
200 — Success: Object created or fetched.
201 — Created: Object created or replaced.
202 — Accepted: Processing asynchronous request.
203 — Non-authoritative Information.
204 — No content.
205 — Reset content.
206 — Partial content.
207 — Multi-status.
208 — Already reported.
226 — Instance-manipulations used.
3xx: redirection
300 — Multiple choices.
301 — Moved permanently.
302 — Found.
303 — See other.
304 — Not modified.
305 — Use proxy.
306 — Switch proxy.
307 — Temporary redirect.
308 — Permanent redirect.
4xx: client errors
400 — Bad request: The request wasn’t valid or can’t be otherwise
served. Typical when there is a syntax error in the request. Further
details of the error are provided in the response payload body.
401 — Unauthorized: Missing or incorrect authentication credentials.
402 — Payment required.
403 — Forbidden: The request is understood, but it was refused or
access was denied. The response payload body provides further details of
the error.
404 — Not found: The URI isn’t valid, or the requested resource doesn’t exist.
405 — Method not allowed: The requested resource doesn’t support the method.
406 — Not acceptable.
407 — Proxy authentication required.
408 — Request timeout.
409 — Conflict.
410 — Gone.
411 — Length required.
412 — Precondition failed.
413 — Payload too large: The request is larger than the server is able to process.
414 — URI too long.
415 — Unsupported media type.
416 — Range can’t be satisfied.
417 — Expectation failed.
418 — I’m a teapot (don’t ask).
421 — Misdirected request.
422 — Entity can’t be processed: The request was well-formed, but the data couldn’t be processed due to semantic errors.
423 — Locked.
424 — Failed dependency.
425 — Too early.
426 — Upgrade required.
428 — Precondition required.
429 — Too many requests.
431 — Request header fields too large.
451 — Unavailable for legal reasons.
5xx: server errors
500 — Internal server error: This is usually a temporary error, for
example in a high load situation or if an endpoint is temporarily having
issues.
