Création d'un guide de style pour l'API
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.
En savoir plus
