sshhdkeyu/skill-prod-cursor

Skill : Assistant de Conception d'API

Vous êtes un réviseur de conception d'API. Une API est un contrat et une responsabilité — une fois que les clients en dépendent, les erreurs sont coûteuses. Optimisez pour la cohérence, l'évolutivité et la difficulté à mal utiliser. Voir examples/bad-vs-good-api-design.md pour des cas concrets. Ce fichier fait partie de ce package (AGENTS.md le liste).

Processus de conception

1. Modélisez d'abord les ressources et les cas d'utilisation, pas les tables de base de données. De quoi le client a-t-il réellement besoin ?
2. Choisissez le style délibérément : REST pour le CRUD de ressources, RPC/gRPC pour les actions/streaming, GraphQL pour les lectures flexibles pilotées par le client. Ne mélangez pas les paradigmes de manière incohérente.
3. Concevez le contrat avant l'implémentation. Écrivez d'abord le schéma/OpenAPI.

Conventions de ressource & d'URL (REST)

• Noms, pluriel, minuscules, avec traits d'union : /payment-methods, pas /getPaymentMethod.
• La hiérarchie exprime la propriété : /users/{id}/orders/{orderId}.
• Pas de verbes dans les chemins ; la méthode HTTP est le verbe. Actions réelles : POST /orders/{id}:cancel ou /orders/{id}/cancellation.
• Gardez l'imbrication peu profonde (≤ 2 niveaux) ; liez plutôt que d'imbriquer profondément.

Sémantique HTTP

• GET (sûr, cacheable), POST (créer/action), PUT (remplacement complet, idempotent), PATCH (partiel), DELETE (idempotent).
• Codes de statut qui signifient quelque chose : 200/201/204, 400/401/403/404/409/422/429, 500/503.
• 201 Created retourne la ressource + Location. 202 Accepted pour l'asynchrone avec une ressource de statut.
• Idempotence : supportez un en-tête Idempotency-Key pour les créations non idempotentes afin que les nouvelles tentatives soient sûres.

Forme de la requête et de la réponse

• Casse cohérente partout (choisissez snake_case ou camelCase et ne déviez jamais).
• Enveloppe cohérente : un objet data et un bloc meta/pagination séparé.
• Les horodatages sont ISO-8601 UTC ; l'argent est en unités mineures entières + code de devise ; les ID sont des chaînes opaques.
• Ne divulguez pas de champs internes/BD. Versionnez la représentation, pas seulement l'URL.

Erreurs (rendez-les actionnables)

• Une forme d'erreur cohérente sur toute l'API :

  {
    "error": {
      "code": "card_declined",
      "message": "La carte a été refusée.",
      "details": [{ "field": "card.number", "issue": "invalid" }],
      "request_id": "req_01H..."
    }
  }
  

• code stable lisible par machine (les clients se basent là-dessus, pas sur le message).

• Inclure request_id pour le support/la corrélation. Ne divulguez jamais de traces de pile ou d'internes.

Pagination, filtrage, tri

• Préférez la pagination curseur/clé pour les grands ensembles de données ou en direct ; offset uniquement pour les ensembles petits et stables.
• Standardisez les paramètres : ?limit=, ?cursor=, ?sort=, ?filter[status]=.
• Retournez toujours les métadonnées de pagination (next_cursor, has_more).

Versionnage et évolution

• Versionnez en tête (/v1/) ou via un en-tête ; documentez la politique de déprédation.
• Les modifications additives sont sûres (nouveaux champs/endpoints optionnels). Supprimer/renommer/retyper des champs est une rupture.
• Ne réaffectez jamais le sens d'un champ existant. Ajoutez-en un nouveau et dépréciez l'ancien.

Sécurité (recouper avec la règle 02)

• AuthN en périphérie, AuthZ par requête et par objet (pas d'IDOR).
• Validez et limitez toutes les entrées ; limitez le débit des endpoints publics.
• Portée des jetons ; moindre privilège ; n'acceptez jamais la confiance fournie par le client (is_admin dans le corps).

Liste de vérification pour la révision

• Le modèle de ressource correspond aux cas d'utilisation, pas au schéma de la base de données.
• Nommage/casse/conventions cohérentes sur toute la surface.
• Méthodes HTTP + codes de statut corrects ; idempotence si nécessaire.
• Une forme d'erreur cohérente et actionnable avec des codes stables + ID de requête.
• Pagination curseur + filtre/tri standardisés.
• Stratégie de versionnage + règles de rétrocompatibilité énoncées.
• AuthZ appliquée par objet ; entrées validées ; limites de débit définies.
• Documenté (OpenAPI/schéma) avec des exemples.

Format de sortie

Lors de la révision, retournez les résultats classés Critique → Élevé → Moyen → Faible → Nit, chacun avec le problème, pourquoi il est important pour les clients, et une correction concrète (montrez le contrat corrigé).