Temps de lecture estimé : 3 min · Publié le 1 octobre 2026
Choisir les tâches avant les adresses
Recensez les usages : chercher un produit, lire une disponibilité, mettre à jour une fiche ou suivre un traitement. Définissez les personnes et systèmes autorisés pour chaque opération. Une API publique en lecture et une API d’administration n’ont pas les mêmes règles d’accès.
Préparez un exemple de demande et de réponse pour chaque tâche essentielle, avec des valeurs fictives et des champs expliqués. Distinguez identifiant stable, libellé, unité et date. Indiquez les données absentes et évitez de remplacer une information inconnue par une valeur plausible.
Décrire un contrat explicite
OpenAPI fournit un format de description des API HTTP indépendant du langage. Il permet de décrire les opérations, paramètres, réponses et modèles. Choisissez une version prise en charge par vos outils et conservez le document avec le projet ; la version la plus récente n’est pas automatiquement la bonne pour chaque chaîne.
Complétez le contrat avec limites d’usage, pagination, filtre, ordre, états d’erreur et exemple de réponse vide. Ne traitez pas CORS comme une preuve d’autorisation : vérifiez les contrôles d’accès propres à chaque opération et chaque objet avec l’équipe technique.
Tester les limites et les permissions
Essayez un objet présent, un objet absent, un paramètre invalide et une liste plus longue qu’une page. Vérifiez que le passage à la page suivante ne perd ni ne répète les objets dans le contexte de mise à jour choisi. Décrivez les limites que votre API ne peut pas garantir.
Utilisez des comptes de test aux droits différents. Tentez une consultation ou modification hors du périmètre autorisé, sans données réelles. Conservez le statut attendu et un message utile, sans révéler au destinataire une trace interne ou un secret de configuration.
Prévoir évolutions et support
Distinguez un champ ajouté d’un champ supprimé ou dont le sens change. Recensez les consommateurs avant une modification incompatible. Expliquez la période de transition et le moyen de vérifier qu’une intégration utilise encore l’ancien contrat.
Livrez un exemple qui s’exécute dans un environnement d’essai, une matrice de tests et un contact technique. Après publication, rapprochez les erreurs observées des exemples documentés. Une documentation qui décrit seulement le cas idéal laisse les intégrateurs seuls face aux refus et interruptions.
Documentation primaire : OpenAPI Initiative — Specification.