@api-designerDesign API REST / GraphQL cohérente
Maifady est un plugin Claude Code 100% gratuit avec 30 agents IA — @api-designer dessine ton API avant que tu codes : ressources, verbes HTTP, status codes précis (pas juste 200/400/500), format d'erreur RFC 7807, pagination cursor, idempotency keys, versioning, auth Bearer. Spec cohérente prête à implémenter.
Le problème qu'il résout
Tu démarres une nouvelle app. Tu pourrais coder direct, mais tu sais que tes premières routes (signup, login) vont fixer le style pour tout le reste — si tu utilises 422 ici et 400 là, ton API sera inconsistante à jamais. Tu veux une spec complète et cohérente avant la première ligne.
@api-designer te livre ça en 15 minutes.
Comment il bosse
- Tu lui décris le domaine (entités + relations).
- Il décide REST vs GraphQL en justifiant (par défaut REST).
- Modèle des ressources comme aggregates, pas tables DB.
- URLs : nouns pluriels, kebab-case, ≤ 2 niveaux de nesting.
- Verbes HTTP avec sémantique correcte (GET safe, POST non-idempotent par défaut, PATCH avec dialect explicite).
- Status codes précis : 201 + Location, 204 No Content, 409 Conflict business vs 412 ETag, 422 vs 400, 429 + Retry-After.
- Format d'erreur uniforme RFC 7807 Problem Details + extensions.
- Pagination cursor (recommandée), idempotency keys, versioning
/v1/, auth Bearer.
Exemple concret
Tu tapes
›@api-designer dessine l'API REST pour une app de réservation de salles. Resources : Users, Rooms, Bookings. Auth Bearer JWT. Multi-tenant.
Tu obtiens
Un doc Markdown complet : diagramme des ressources, tous les endpoints avec body/response, status codes (200, 201, 204, 400, 401, 403, 404, 409, 422, 429), format d'erreur RFC 7807, pagination cursor, idempotency sur POST /bookings, versioning /v1/, auth, exemples curl. Prêt à coder.
Pourquoi tu vas l'aimer
Cohérent par construction
Toutes les routes suivent le même format d'erreur, la même pagination, le même versioning. Pas de surprise.
Status codes précis
409 vs 412 vs 422 vs 400 — l'agent les utilise correctement. Les clients comprennent.
Idempotency built-in
POST /payments avec Idempotency-Key dès le départ. Pas de double-charge en cas de retry.
Versionable
/v1/ + plan de déprécation. Ton API peut évoluer sans casser les clients.
Quand l'utiliser
✅ Idéal pour
- Nouvelle API à concevoir avant de coder
- API publique exposée à des consumers externes
- Refonte v2 d'une API qui est devenue inconsistante
- Review d'une API existante (audit de cohérence)
⚠️ Pas adapté quand
- Tu veux générer OpenAPI depuis du code existant → @openapi-generator
- Tu veux documenter ton API → @api-doc-generator
- Tu veux découper en microservices → @microservices-architect
Combine avec ces agents
Questions fréquentes
REST ou GraphQL ?
REST par défaut. GraphQL uniquement si le client a besoin de sélection flexible de champs, traversal profond du graph, ou multiples vues hétérogènes sur les mêmes données.
Quel format d'erreur ?
RFC 7807 Problem Details + extensions : type, title, status, code (machine-parsable), detail, instance, request_id, errors[] par-field.