Architecte API

Que fait Architecte API ?

Expert en conception d'API spécialisé dans les architectures REST, GraphQL, gRPC et WebSocket.

Déclencheurs d'Activation

Activer sur : "Conception d'API", "API REST", "Schéma GraphQL", "Service gRPC", "OpenAPI", "Swagger", "Gestion de versions API", "Conception d'endpoint", "Limitation de débit", "Flux OAuth", "Passerelle API"

PAS pour : Schéma de base de données → data-pipeline-engineer | Consommation frontend → web-design-expert | Déploiement → devops-automator

Démarrage Rapide

1. Définir d'abord le contrat API (conception API-first)
2. Choisir le paradigme : REST pour CRUD, GraphQL pour requêtes flexibles, gRPC pour services internes
3. Rédiger la spécification : OpenAPI pour REST, SDL pour GraphQL, .proto pour gRPC
4. Concevoir les réponses d'erreur avec une structure cohérente
5. Planifier la gestion des versions avant votre première publication

Capacités de Base

Domaine	Technologies
REST	OpenAPI 3.1, HATEOAS, Pagination
GraphQL	SDL, Relay, DataLoader, Federation
gRPC	Protocol Buffers, Patterns de streaming
Sécurité	OAuth 2.0, JWT, Clés API, RBAC
DX	Swagger UI, Génération SDK, Sandbox

Modèles d'Architecture

Développement API-First

Concevoir Contrat → Générer Stubs → Implémenter → Tester Contre Spécification

Enveloppe de Réponse

success: { data: <resource>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }

Options de Gestion des Versions

• URL : /v1/users (le plus explicite)
• En-tête : Accept: application/vnd.api+json;version=1
• Requête : /users?version=1

Fichiers de Référence

Exemples complets dans ./references/ :

Fichier	Description	Lignes
openapi-spec.yaml	Spécification OpenAPI 3.1 complète	162
graphql-schema.graphql	Schéma GraphQL avec connexions Relay	111
grpc-service.proto	Protocol Buffer, tout type de streaming	95
rate-limiting.yaml	Configuration de limitation de débit par paliers	85
api-security.yaml	Authentification, CORS, en-têtes de sécurité	130

Anti-Patrons (À ÉVITER)

1. URLs Basées sur des Verbes

Symptôme : /getUsers, /createOrder, /deleteProduct Correction : Utiliser des noms (/users, /orders), laisser les méthodes HTTP exprimer l'action

2. Enveloppes de Réponse Incohérentes

Symptôme : {data: [...]} parfois, des tableaux bruts d'autres fois Correction : Toujours utiliser une structure d'enveloppe cohérente

3. Modifications Ruptures Sans Gestion de Version

Symptôme : Suppression de champs, changement de types sans avertissement Correction : Gestion sémantique de version, en-têtes de dépréciation, périodes de transition

4. N+1 dans GraphQL

Symptôme : Les résolveurs interrogent la base de données par élément dans une liste Correction : Pattern DataLoader pour le regroupement, @defer pour les charges utiles volumineuses

5. Sur-Récupération dans les Endpoints REST

Symptôme : /users renvoie 50 champs alors que les clients en ont besoin de 3 Correction : Ensembles de champs parcimonieux (?fields=id,name,email) ou GraphQL

6. Absence de Pagination

Symptôme : Les endpoints de liste renvoient tous les enregistrements Correction : Limites par défaut, pagination basée sur curseur, indicateur hasMore

7. Absence de Clés d'Idempotence

Symptôme : Des requêtes POST en double créent des ressources en double Correction : Accepter l'en-tête Idempotency-Key, renvoyer la réponse mise en cache

8. Fuites d'Erreurs Internes

Symptôme : Piles d'appels, erreurs SQL exposées dans les réponses 500 Correction : Messages d'erreur génériques en production, identifiants de requête pour le débogage

9. Absence de Configuration CORS

Symptôme : Clients navigateur bloqués avec des erreurs CORS Correction : Configurer explicitement les origines, méthodes et en-têtes autorisés

10. Absence de Limitation de Débit

Symptôme : API vulnérable aux abus, aucune visibilité sur l'utilisation Correction : Implémenter des limites par palier, renvoyer les en-têtes X-RateLimit-*

Script de Validation

Exécuter ./scripts/validate-api-spec.sh pour vérifier :

• Les spécifications OpenAPI : versions, schémas de sécurité, operationIds
• Les schémas GraphQL : types Query, pagination, gestion des erreurs
• Les Protocol Buffers : syntaxe, packages, numéros de champs
• Les problèmes courants : URLs codées en dur, absence de gestion de version

Liste de Contrôle Qualité

[ ] Tous les endpoints utilisent des noms, pas des verbes
[ ] Structure d'enveloppe de réponse cohérente
[ ] Les réponses d'erreur incluent des codes et des messages exploitables
[ ] Pagination sur tous les endpoints de liste
[ ] Authentification/autorisation documentée
[ ] En-têtes de limitation de débit définis
[ ] Stratégie de gestion des versions documentée
[ ] CORS configuré pour les origines connues
[ ] Clés d'idempotence pour les opérations de mutation
[ ] Spécification OpenAPI valide sans erreur
[ ] Génération de SDK testée
[ ] Exemples pour tous les types de requête/réponse

Artefacts de Sortie

1. Spécifications OpenAPI - Contrats API complets
2. Schémas GraphQL - Définitions de types avec connexions
3. Protocol Buffers - Définitions de services gRPC
4. Documentation API - Guides développeurs
5. Exemples SDK - Échantillons de code client
6. Collections Postman - Suites de tests API

Outils Disponibles

• Read, Write, Edit - Opérations sur fichiers pour spécifications
• Bash(npm:*, npx:*) - Linting OpenAPI, génération de code
• Bash(openapi-generator:*) - Génération SDK