Versionnage et dépréciation
Ce qui peut évoluer dans la version v1, ce qui n'y change jamais, le statut bêta et la façon dont une version est dépréciée.
Documentation de l'APIGuides · Versionnage
Une version dans l'adresse
La version fait partie de l'adresse : https://api.mabellenote.com/v1. La version v1 n'évolue que par ajout. Une évolution incompatible crée une nouvelle version, par exemple /v2, qui coexiste avec la précédente.
Ce qui peut arriver dans v1
Ces évolutions ne sont pas cassantes et peuvent arriver à tout moment :
- une nouvelle opération ;
- un nouveau paramètre facultatif ;
- un nouveau champ dans une réponse ;
- une nouvelle valeur dans une énumération ;
- un nouveau type d'événement ;
- un nouveau code d'erreur, sur une nouvelle opération ;
- un paramètre obligatoire qui devient facultatif ;
- une limite relevée.
Ce qui ne change jamais dans v1
- Une opération, un champ ou une valeur d'énumération n'est ni retiré ni renommé.
- Le type ou le format d'un champ ne change pas.
- Un paramètre facultatif ne devient pas obligatoire.
- Un champ toujours renseigné ne devient pas facultatif ni
null. - Le sens d'un champ, le statut ou le code d'une erreur, et le droit requis par une opération restent les mêmes.
Écrire une intégration robuste
- Ignorez les champs que vous ne connaissez pas.
- Toutes les énumérations sont ouvertes : prévoyez un traitement par défaut pour une valeur inconnue.
- Un champ documenté est toujours présent, à
nullquand il est vide. - Les identifiants sont des chaînes opaques : ne les interprétez pas.
- Les dates sont des chaînes ISO 8601 en UTC, avec les millisecondes.
Opérations en bêta
Une opération marquée « Bêta » dans la référence (x-stability: beta dans la description OpenAPI) peut encore évoluer avant d'être déclarée stable : elle n'est pas couverte par les garanties ci-dessus. Les lectures sont stables ; le journal d'événements, les webhooks, les écritures et la publication sur Google sont en bêta. Le tableau ci-dessous, tiré de la description OpenAPI, donne la stabilité de chaque opération.
| Opération | Rôle | Droit requis | Stabilité |
|---|---|---|---|
GET /v1/health | Vérifier la disponibilité de l'API | Sans clé | Stable |
GET /v1/openapi.json | Obtenir la description OpenAPI | Sans clé | Stable |
GET /v1/me | Identifier la clé API | account:read | Stable |
GET /v1/establishments | Lister les établissements | establishments:read | Stable |
GET /v1/establishments/{establishmentId} | Obtenir un établissement | establishments:read | Stable |
GET /v1/establishments/{establishmentId}/stats | Obtenir les statistiques d'un établissement | stats:read | Stable |
GET /v1/reviews | Lister les avis | reviews:read | Stable |
GET /v1/reviews/{reviewId} | Obtenir un avis | reviews:read | Stable |
GET /v1/feedbacks | Lister les retours privés | feedbacks:read | Stable |
GET /v1/feedbacks/{feedbackId} | Obtenir un retour privé | feedbacks:read | Stable |
GET /v1/contacts | Lister les contacts | contacts:read | Stable |
POST /v1/contacts | Créer ou mettre à jour un contact | contacts:write | Bêta |
GET /v1/contacts/{contactId} | Obtenir un contact | contacts:read | Stable |
PATCH /v1/contacts/{contactId} | Modifier un contact | contacts:write | Bêta |
POST /v1/visits | Enregistrer un passage | visits:write | Bêta |
POST /v1/promo-codes/redeem | Valider un code promo | promo_codes:redeem | Bêta |
POST /v1/reviews/{reviewId}/reply-drafts | Générer un brouillon par l'IA | ai:generate | Bêta |
PUT /v1/reviews/{reviewId}/reply-draft | Déposer un brouillon rédigé | replies:write | Bêta |
POST /v1/reviews/{reviewId}/reply | Publier une réponse sur Google | replies:publish | Bêta |
GET /v1/events | Lister les événements | events:read | Bêta |
GET /v1/events/{eventId} | Obtenir un événement | events:read | Bêta |
GET /v1/webhook-endpoints | Lister les points de réception | webhooks:manage | Bêta |
POST /v1/webhook-endpoints | Créer un point de réception | webhooks:manage | Bêta |
DELETE /v1/webhook-endpoints/{endpointId} | Supprimer un point de réception | webhooks:manage | Bêta |
POST /v1/webhook-endpoints/{endpointId}/test | Envoyer un événement de test | webhooks:manage | Bêta |
Dépréciation d'une version
Quand une nouvelle version majeure paraît :
- L'ancienne version reste servie à l'identique pendant au moins 12 mois.
- Ses réponses portent les en-têtes
Deprecation(RFC 9745) etSunset(RFC 8594), qui donne la date de fin, ainsi qu'un en-têteLinkvers le journal des changements (rel="deprecation"). - Les propriétaires et administrateurs des comptes qui utilisent encore l'ancienne version sont prévenus par email.
- Après la date de fin, l'ancienne version répond
410 Gone, avec une erreur qui renvoie vers le guide de migration.
Chaque évolution du contrat est datée dans le journal des changements de l'API.
Description OpenAPI
GET /v1/openapi.json renvoie la description OpenAPI 3.1 de la version, sans clé. Le paramètre lang choisit la langue des descriptions (en par défaut, ou fr). Elle sert à générer un client ou à importer l'API dans un outil de test.
Mis à jour le 25 octobre 2026