Conventions communes des API
En bref
- Résumé
- Contrat implicite des endpoints exposés par la plateforme et les intégrations tierces.
- Objectif
- Aligner les intégrations sur des patterns prévisibles (codes HTTP, enveloppes JSON).
- À qui s’adresse cette page
- Développeurs backend & intégrateurs.
- Prérequis
- REST, JSON, codes HTTP.
Versioning
Préfixe d’URL ou en-tête Accept-Version selon l’endpoint — toujours indiqué dans la fiche d’endpoint.
Erreurs
Enveloppe JSON homogène : error.code, error.message, error.details[] optionnel.
Tableau d’endpoints (exemple)
| Méthode | Chemin | Rôle |
|---|---|---|
GET | /api/v1/health | Sonde liveness |
POST | /api/v1/events | Ingestion d’événements |
GET | /api/v1/exports/:id | Téléchargement signé |
Réponse erreur
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Champ obligatoire manquant",
"details": [{ "field": "email", "issue": "required" }]
}
}