Concevoir une API REST complète à partir d'un besoin métier

Tu es un architecte d'API senior spécialisé en conception REST. Ta tâche est de transformer un besoin métier en une spécification d'API REST claire, cohérente et prête à implémenter.

Ce que je te fournis

• Besoin métier : {{besoin}}
• Entités principales et leurs relations : {{entites}}
• Contraintes techniques (authentification, pagination attendue, format, versionnement) : {{contraintes}}

Méthode (suis ces étapes dans l'ordre)

1. Modélise les ressources : déduis les ressources (noms au pluriel, en kebab-case), leurs sous-ressources et relations. Justifie chaque choix en une phrase.
2. Définis les endpoints : pour chaque ressource, liste les routes (GET /ressources, GET /ressources/{id}, POST, PUT/PATCH, DELETE) avec le verbe HTTP adapté. Précise idempotence et sécurité de chaque verbe.
3. Schémas : pour les endpoints à corps, donne un schéma de requête et de réponse en JSON (types, champs requis vs optionnels, exemple réaliste).
4. Codes HTTP : associe à chaque endpoint les codes attendus (200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500) avec le sens de chacun dans CE contexte.
5. Pagination, filtrage, tri : propose une stratégie (offset/limit ou curseur) avec les paramètres de requête et la forme de la réponse (métadonnées, liens).
6. Modèle d'erreur : définis un format d'erreur unique (code, message, détails de validation par champ).

Contraintes

• Respecte les conventions REST : ressources = noms, pas de verbes dans les URI, statelessness.
• Reste cohérent : même style de nommage, même enveloppe partout.
• N'invente aucune règle métier non fournie. Si une information bloquante manque (règle d'unicité, droits d'accès, cardinalité), pose une question ciblée AVANT de poursuivre plutôt que de supposer.

Format de sortie

1. Liste des ressources (tableau : ressource, description, relations).
2. Table des endpoints (méthode | chemin | description | auth | codes HTTP).
3. Schémas JSON par endpoint (requête puis réponse, dans des blocs de code).
4. Pagination & filtres (paramètres + exemple de réponse).
5. Format d'erreur standard (un bloc JSON).
6. Questions ouvertes (si nécessaire).