Cycle de vie des endpoints
Chaque endpoint porte un stade de maturité. Ce n'est pas une mention en prose : c'est dans le contrat, donc votre outillage peut le lire.
| Stade | Ce que cela implique pour vous |
|---|---|
| Beta | Disponible, mais le contrat peut encore changer. Exige un scope supplémentaire. Pas pour la production. |
| GA | Disponible en général. Couvert par la garantie de versionnement — voir Versionnement. |
| Déprécié | Toujours servi, en fin de vie. Les réponses portent Deprecation et Sunset. |
Le lire depuis le contrat
Le document OpenAPI expose le stade via une extension x-lifecycle sur chaque opération, et les opérations
dépréciées positionnent en plus le drapeau standard deprecated. La référence l'affiche endpoint par
endpoint, et un client généré peut le remonter sans avoir à le demander à quiconque.
Aucun endpoint n'est en Beta aujourd'hui
Tous les endpoints de cette API sont en GA : aucun n'exige le scope beta:access. Le stade reste dans le
contrat pour ce que nous ajouterons plus tard, et la règle ci-dessous est la façon dont il fonctionnera alors.
Les endpoints Beta sont gardés
Appeler un endpoint Beta exige le scope beta:access en plus des scopes propres à l'endpoint. Sans
lui, l'appel est refusé :
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{ "type": "scopes/insufficient", "detail": "Scope 'beta:access' required", … }
C'est délibéré. Cela garantit que personne n'intègre par accident un contrat instable, et cela nous donne la liste précise des partenaires à prévenir quand un contrat Beta évolue.
Demandez beta:access à votre interlocuteur Staff & Go si vous voulez en essayer un — et pensez à demander
le scope explicitement sur le jeton, voir Authentification.
Sur quoi construire
Pour tout ce qui va en production, construisez sur du GA. La Beta sert à évaluer ce qui arrive et à nous dire ce qui ne va pas tant que le corriger coûte encore peu.
Si une capacité dont vous avez besoin n'existe qu'en Beta, dites-le. Les retours pendant la Beta décident de la forme qu'elle emportera en GA — après quoi la changer coûte une montée de version à tout le monde.