OpenAPI

Consigner un contrat d’API HTTP compréhensible

OpenAPI est un standard de description des API HTTP. Une description OpenAPI précise notamment les chemins, opérations, paramètres et structures de réponse proposés. Elle peut être représentée en JSON ou en YAML. Le langage de description ne dépend pas du langage de programmation utilisé pour construire le service.

Une entreprise de logiciels fictive prévoit GET /projects/{projectId} pour son portail de projets. La description doit définir projectId comme paramètre de chemin ; la réponse réussie 200 doit comprendre notamment le champ texte name. Les réponses d’erreur connues font aussi partie du contrat. Le chemin et les champs sont nos propres exemples de conception, pas un document OpenAPI complet ni un service existant.

L’équipe frontend peut ainsi comprendre les informations à envoyer et les réponses à traiter. Le fichier seul ne montre toutefois pas si l’implémentation en fonctionnement respecte ce contrat. Avant la remise, description et réponses réelles, y compris les erreurs, seraient à comparer. Le sens de name doit aussi être convenu : une chaîne correctement typée ne précise pas quel nom contient le champ.

Sources

• OpenAPI Initiative · OpenAPI Specification