Développement REST & OpenAPI pour des API bien documentées et maintenables

OpenAPI 2 (Swagger) utilise un objet definitions séparé et offre un support limité des fonctionnalités modernes de JSON Schema. OpenAPI 3.0 a introduit les components, requestBody et les types de médias de réponse multiples. OpenAPI 3.1 s'aligne entièrement avec JSON Schema Draft 2020-12 — supportant nullable (null dans le tableau type), if/then/else, const et deprecated dans les schémas. Nous utilisons OpenAPI 3.1 pour tous les nouveaux projets et migrons les anciennes spécifications vers la 3.1 lors des revues d'API.

Nous utilisons le versionnage par préfixe d'URL (/v1/, /v2/) comme stratégie principale — il est explicite, mis en cache et visible dans les journaux et les passerelles API. Le versionnage par en-tête (Accept: application/vnd.api.v2+json) est utilisé lorsque la stabilité de l'URL est importante (intégrations partenaires). Nous maintenons la version précédente pendant une fenêtre de dépréciation documentée (généralement 6 à 12 mois), ajoutons les en-têtes de réponse Sunset et Deprecation aux endpoints dépréciés et générons un journal des modifications à partir des diffs de spécifications OpenAPI.

Des outils spécifiques à chaque langage génèrent OpenAPI à partir d'annotations de code : Springdoc OpenAPI pour Spring Boot (Java), la génération de schéma intégrée de FastAPI (Python), tsoa ou ts-rest pour TypeScript, oapi-codegen pour Go. Nous exécutons le linting Spectral OpenAPI en CI pour imposer les conventions de nommage, les descriptions requises, les valeurs d'exemple et l'exhaustivité des schémas de sécurité. La spécification générée est committée dans le dépôt et publiée sur un portail développeur à chaque release.

Le contract testing valide qu'une implémentation serveur correspond au contrat défini dans la spécification OpenAPI. Nous utilisons Prism (Stoplight) comme serveur mock — les équipes consommatrices écrivent des tests contre Prism et le vrai serveur pendant le développement. Dredd ou Schemathesis exécute la spécification OpenAPI comme suite de tests contre le serveur live en CI — testant chaque endpoint, méthode et code de réponse défini dans la spécification. Une porte CI empêche le merge si l'implémentation diverge de la spécification.

OAuth2 avec PKCE pour les API orientées utilisateur ; flux client credentials pour les communications service-à-service ; validation JWT au niveau de la passerelle API (Kong, AWS API Gateway) avec autorisation des endpoints basée sur les scopes. Limitation de débit par client_id et par IP via compteur Redis. Validation des entrées au niveau du schéma (validation JSON Schema avant l'exécution du handler). CORS restreint aux origines connues. Messages d'erreur verbeux supprimés (pas de traces de pile, pas de détails de service interne). Revue OWASP API Security Top 10 avant chaque lancement externe.

Un proxy inverse (Nginx, HAProxy) route les requêtes HTTP, termine le TLS et équilibre la charge — il n'a aucune connaissance spécifique aux API. Une passerelle API (Kong, AWS API Gateway, Azure APIM) ajoute un middleware spécifique aux API : plugin d'authentification (validation JWT/OAuth2), limitation de débit par consommateur, transformation requête/réponse, journalisation par endpoint, portail développeur et routage de versionnage d'API. Nous utilisons Nginx comme proxy inverse en périphérie et Kong ou AWS API Gateway comme couche de passerelle API pour les préoccupations spécifiques aux API.

L'OWASP API Security Top 10 est la liste de contrôle de référence pour les vulnérabilités d'API : 1) Broken Object Level Authorisation (BOLA — accès aux objets d'autres utilisateurs) ; 2) Authentification défaillante ; 3) Broken Object Property Level Authorisation (affectation de masse) ; 4) Consommation de ressources non restreinte (limitation de débit manquante) ; 5) Broken Function Level Authorisation (endpoints admin accessibles aux utilisateurs) ; 6) Accès non restreint aux flux métier sensibles ; 7) Server-Side Request Forgery (SSRF) ; 8) Mauvaise configuration de sécurité ; 9) Gestion d'inventaire incorrecte (API fantômes) ; 10) Consommation non sécurisée d'API. Nous testons chaque nouvelle API contre les 10 points avant tout lancement externe.