FAQ
Doc-first, contract-first, API-first : quelle différence ?
Les trois termes sont quasi-synonymes. Doc-first met l'accent sur la documentation comme livrable, contract-first sur le contrat d'interface, API-first sur la priorité organisationnelle. En pratique, tous désignent une démarche où la spec OpenAPI précède le code.
Pourquoi RFC 7807 Problem Details ?
C'est un standard IETF (2016) qui définit un format JSON normalisé pour les erreurs HTTP : type, title, status, detail, instance. Adopté par .NET, Spring, et la plupart des frameworks modernes. Il évite à chaque équipe de réinventer son format d'erreur.
Quel impact sur les performances ?
Le middleware charge la spec une seule fois au démarrage et travaille sur des objets en mémoire. Surcoût négligeable par requête (validation regex + lookup de schéma).
Comment versionner l'OpenAPI ?
Dans notre cas, le fichier OpenAPI vit dans un repo dédié, versionné en sémantique. Les services consommateurs référencent une version précise via NuGet. Une PR sur la spec déclenche les tests de tous les services concernés.
Et pour les workers (consommateurs Service Bus) ?
Les workers n'exposent pas d'API HTTP mais utilisent les mêmes libs communes pour les logs et le formatage d'erreurs. La spec OpenAPI ne s'applique qu'aux endpoints REST.
Qu'est-ce qu'une approche API-first ?
L'approche API-first est une démarche de conception où l'API est traitée comme un produit à part entière, conçue et spécifiée avant tout développement applicatif. Concrètement, l'équipe rédige le contrat (généralement en OpenAPI) en amont, le fait valider par tous les consommateurs (front, partenaires, mobile, services internes), puis seulement après écrit le code côté serveur et côté client en parallèle. Bénéfices : parallélisation des équipes, contrats stables, tests dérivables de la spec, documentation toujours à jour. C'est l'inverse de l'approche code-first, où l'on écrit le code d'abord et où la documentation est générée a posteriori, souvent avec des écarts entre ce qui est documenté et ce qui est livré.
OpenAPI vs Swagger : quelle différence ?
Swagger était à l'origine (2011) à la fois une spécification et un ensemble d'outils créés par SmartBear. En 2015, la spécification a été donnée à la Linux Foundation et renommée OpenAPI Specification (OAS). C'est aujourd'hui le standard officiel, maintenu par l'OpenAPI Initiative (voir la structure de gouvernance). Le nom Swagger désigne désormais uniquement la suite d'outils de SmartBear (Swagger UI, Swagger Editor, Swagger Codegen). En résumé : on écrit une spec OpenAPI ; on la visualise avec Swagger UI. Les deux termes restent souvent utilisés de manière interchangeable dans le langage courant, mais la distinction est utile en contexte technique précis.
Comment versionner une API REST en production ?
Trois stratégies dominent, avec des compromis distincts :
- Versioning par URL (ex. /v1/devices, /v2/devices) : le plus visible et le plus simple à router. Inconvénient : couplage fort entre la version et l'URI, ce qui complique les redirections et la coexistence.
- Versioning par header (ex. Accept: application/vnd.kaizen.v2+json) : propre du point de vue REST, l'URI reste stable. Inconvénient : moins explorable, plus difficile à tester dans un navigateur.
- Versioning par paramètre de requête (ex. ?api-version=2.0) : souvent utilisé chez Microsoft / Azure, simple à mettre en place. Inconvénient : pollue les logs et les analytics.
Recommandations transverses : adopter le SemVer côté spec OpenAPI (MAJOR.MINOR.PATCH), ne jamais introduire de breaking change sans bump majeur, publier une politique de dépréciation explicite (par ex. 12 mois de support sur la version N-1), et automatiser la détection des breaking changes en CI (outils : oasdiff, openapi-diff). Sur notre projet, nous utilisons le versioning par paramètre de requête (héritage de l'écosystème Azure) avec un bump majeur sur la spec à chaque rupture de contrat.