Concevoir une API REST avec spécification OpenAPI

Prompt

Agis comme un architecte d'API expérimenté dans la conception d'API REST publiques utilisées par des tiers.

Je construis l'API de {{product}}.
Principaux consommateurs : {{consumers}}.
Entités et relations connues : {{entities}}.
Exigences non fonctionnelles : {{requirements}}.

Livre, dans cet ordre :
1. Le modèle de ressources : la liste des ressources, leurs attributs clés, leurs relations et l'identifiant utilisé par chacune.
2. Un tableau des endpoints (méthode, chemin, description, authentification requise, codes de statut possibles). Utilise des noms au pluriel, un seul niveau d'imbrication au maximum, et justifie les actions qui ne relèvent pas du CRUD.
3. Les conventions : nommage des champs ({{naming_convention}}), dates ISO 8601 en UTC, pagination par curseur, filtrage, tri et champs partiels (sparse fieldsets).
4. Un format d'erreur unique fondé sur la RFC 9457 (Problem Details), avec des exemples pour 400, 401, 403, 404, 409, 422 et 429.
5. La stratégie de versionnage, l'idempotence (en-tête `Idempotency-Key` sur les POST) et le contrôle de concurrence (ETag / If-Match).
6. La sécurité : schéma d'authentification, portées de permissions (scopes) et limites de débit.
7. Un extrait YAML OpenAPI 3.1 couvrant les deux ressources principales, leurs schémas et des réponses d'erreur réutilisables dans `components`.
8. Les risques de conception et les décisions à revoir avec l'équipe.

Contraintes :
- N'invente pas de règles métier : si quelque chose n'est pas clair, marque-le [À COMPLÉTER] et pose-moi la question.
- Privilégie la cohérence plutôt que la créativité.

Comment l'utiliser

Exemple d'utilisation

Exemple de résultat

openapi: 3.1.0
info: { title: Clinic Booking API, version: 1.0.0 }
paths:
  /appointments:
    post:
      parameters:
        - { in: header, name: Idempotency-Key, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Appointment' }
      responses:
        '201': { description: Rendez-vous créé }
        '409': { $ref: '#/components/responses/Problem' }
        '422': { $ref: '#/components/responses/Problem' }
components:
  schemas:
    Appointment:
      type: object
      required: [practitioner_id, patient_id, starts_at]
      properties:
        id: { type: string, readOnly: true }
        practitioner_id: { type: string }
        patient_id: { type: string }
        starts_at: { type: string, format: date-time }
  responses:
    Problem:
      description: Erreur au format RFC 9457
      content:
        application/problem+json:
          schema: { type: object, properties: { type: { type: string }, title: { type: string }, status: { type: integer }, detail: { type: string } } }

Informations clés

Catégorie

Programmation et développement · API

Type de résultat

Code

Niveau

Avancé

Conçu pour

ChatGPT, Claude et Gemini

Vérifié sur

En attente de vérification éditoriale

Variables

Produit, Consommateurs, Entités, Exigences non fonctionnelles et Convention de nommage

Langue

Français

Prix

Gratuit, sans inscription

Mis à jour

07/11/2026

Questions fréquentes