Générateur de blueprint de conception d'API RESTful

Vous êtes un architecte d'API qui a conçu des API utilisées par des millions de développeurs dans des entreprises comme Stripe, Twilio et GitHub. Vos API sont réputées pour être intuitives, cohérentes et conviviales pour les développeurs. Vous suivez les meilleures pratiques REST tout en restant pragmatique face aux besoins réels. J'ai besoin que vous conceviez une API complète pour ce qui suit : ## Exigences du Projet Objectif de l'API : [DÉCRIVEZ CE QUE FAIT L'API] Utilisateurs Cibles : [QUI VA UTILISER CETTE API] Ressources Principales : [LISTEZ LES PRINCIPALES ENTITÉS, ex. Users, Products, Orders] Méthode d'Authentification : [API KEY / OAuth 2.0 / JWT / etc.] Échelle Attendue : [REQUÊTES PAR SECONDE / NOMBRE D'UTILISATEURS] ## Générez un Document Complet de Conception d'API : ### 1. VUE D'ENSEMBLE DE L'API - Nom et version de l'API (ex. v1) - Recommandation de structure d'URL de base - Content-Type (JSON supposé, indiquer les exceptions) - Style d'API (REST, avec notes sur d'éventuels endpoints de type RPC) - Recommandation de stratégie de rate limiting ### 2. AUTHENTIFICATION ET AUTORISATION Concevez le système d'authentification : - Détails de la méthode d'authentification - Format et cycle de vie du token - Stratégie de refresh token (le cas échéant) - Modèle de scopes/permissions - Exemple de headers d'authentification ``` Authorization: Bearer <token> X-API-Key: <api_key> ``` ### 3. CONCEPTION DES RESSOURCES Pour chaque ressource principale, définissez : #### Ressource : [NOM] - Description - Relations avec d'autres ressources - Format de l'identifiant unique (UUID, slug, auto-incrément) **Endpoints :** ``` GET /[resources] - List all (with pagination) GET /[resources]/:id - Get single resource POST /[resources] - Create new resource PUT /[resources]/:id - Full update PATCH /[resources]/:id - Partial update DELETE /[resources]/:id - Delete resource ``` **Schéma de Données :** ```json { "id": "string (uuid)", "created_at": "string (ISO 8601)", "updated_at": "string (ISO 8601)", // ... resource-specific fields } ``` **Tableau de Définition des Champs :** | Champ | Type | Requis | Description | Contraintes | |-------|------|--------|--------------|-------------| ### 4. FORMATS DE REQUÊTE/RÉPONSE **Réponse de Succès Standard :** ```json { "data": { ... }, "meta": { "request_id": "req_abc123", "timestamp": "2024-01-15T10:30:00Z" } } ``` **Réponse de Liste (avec pagination) :** ```json { "data": [ ... ], "pagination": { "total": 100, "page": 1, "per_page": 20, "total_pages": 5, "next_cursor": "eyJpZCI6MTAwfQ==", "has_more": true }, "meta": { ... } } ``` **Paramètres de Requête pour les Listes :** - `page` / `cursor` - Pagination - `per_page` / `limit` - Éléments par page (max 100) - `sort` - Champ de tri - `order` - asc/desc - `filter[field]` - Filtrage - `include` - Ressources liées à inclure - `fields` - Sparse fieldsets (sélection de champs) ### 5. GESTION DES ERREURS **Format de Réponse d'Erreur :** ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human readable message", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Email must be a valid email address" } ], "request_id": "req_abc123", "documentation_url": "https://api.example.com/docs/errors#VALIDATION_ERROR" } } ``` **Codes d'Erreur Standard :** | Statut HTTP | Code d'Erreur | Description | |-------------|----------------|-------------| | 400 | VALIDATION_ERROR | Échec de la validation de la requête | | 401 | UNAUTHORIZED | Authentification manquante ou invalide | | 403 | FORBIDDEN | Authentification valide mais permissions insuffisantes | | 404 | NOT_FOUND | La ressource n'existe pas | | 409 | CONFLICT | Conflit d'état de la ressource | | 422 | UNPROCESSABLE | Syntaxe valide mais erreur sémantique | | 429 | RATE_LIMITED | Trop de requêtes | | 500 | INTERNAL_ERROR | Erreur serveur | ### 6. STRATÉGIE DE VERSIONING - Versioning par URL : `/v1/resources` - Option de versioning par header : `API-Version: 2024-01-15` - Politique de dépréciation - Modèle de guide de migration ### 7. CONCEPTION DE LA PAGINATION Choisissez et documentez : - Basée sur offset : `?page=2&per_page=20` - Basée sur curseur : `?cursor=eyJpZCI6MTAwfQ==` - Keyset : `?after_id=100` Incluez les avantages/inconvénients de l'approche choisie. ### 8. FILTRAGE ET RECHERCHE Concevez des modèles de requête : ``` GET /products?filter[category]=electronics GET /products?filter[price][gte]=100&filter[price][lte]=500 GET /products?search=keyword GET /products?status=active,pending ``` ### 9. RATE LIMITING - Niveaux de rate limit (par plan/niveau d'authentification) - Headers à retourner : - `X-RateLimit-Limit` - `X-RateLimit-Remaining` - `X-RateLimit-Reset` - Header Retry-After sur le code 429 ### 10. WEBHOOKS (le cas échéant) - Types d'événements - Format du payload - Vérification de signature - Politique de nouvelles tentatives ### 11. SPÉCIFICATION OPENAPI Générez le YAML OpenAPI 3.0 pour les endpoints principaux : ```yaml openapi: 3.0.0 info: title: [API Name] version: 1.0.0 paths: /[resource]: get: summary: List [resources] # ... complete specification ``` ### 12. CONSIDÉRATIONS SUR LE SDK - Modèles de SDK recommandés - Nommage idiomatique selon les langages - Attentes en matière de gestion des erreurs - Helpers de pagination Rendez toutes les conceptions cohérentes, en suivant les standards de l'industrie. Justifiez les décisions de conception. Incluez des exemples curl pour les endpoints clés.