Versions et dépréciation

Ce qui peut changer sans préavis, comment un changement incompatible est publié et annoncé, et les limites de débit

Versionnement

La version de l'API fait partie de l'adresse de chaque opération : les opérations actuelles sont servies sous /v1 (par exemple https://api.marvins.ai/v1/partner/projects).

Exception : le flux XML « Site web » (/public/feeds/site-web/{tenantSlug}.xml) n'a pas de version dans son adresse. Il suit la même politique, décrite ci-dessous.

Ce qui change sans préavis

Les ajouts compatibles sont publiés à la même adresse, sans préavis :

une nouvelle opération ;
un nouveau champ dans une réponse JSON ;
un nouveau paramètre ou champ de requête facultatif ;
une nouvelle balise dans un flux XML, annoncée par e-mail aux administrateurs des cabinets qui utilisent ce flux.

Ignorez les champs et les balises que vous ne connaissez pas, et ne dépendez pas de leur position (sauf pour le cas de nom en double décrit plus bas) : un client qui refuse un élément inconnu cassera au premier ajout.

Ce qui exige une nouvelle version

Est un changement incompatible :

le retrait d'une opération ou d'un champ ;
le changement de type ou de format d'un champ (un nombre devenu texte, un autre format de date…) ;
un nouveau paramètre ou champ de requête obligatoire ;
dans un flux XML : tout changement que Marvin apporte à ce qu'il produit (voir ci-dessous).

Flux XML. L'engagement porte sur ce que Marvin produit : le nom des balises standard, le format et le sens de leurs valeurs, la construction des identifiants et la règle qui nomme les balises des champs personnalisés. Ce que le cabinet change n'est pas un changement d'API : les valeurs suivent ses offres et ses réglages (<uniqueid> reprend la référence de l'offre ; <lat>, <lng> ou <logoUrl> n'apparaissent que si la donnée existe), et les balises de ses champs personnalisés apparaissent, changent de nom ou disparaissent avec eux. Si l'une porte le nom d'une balise standard (un champ « Job ID » donne un second <jobid>), lisez la première occurrence quand la balise standard est présente : elle est émise avant les champs personnalisés, sauf <lastactivitydate>.

Un changement incompatible n'est jamais appliqué à une adresse existante : il est publié tout de suite sous une nouvelle adresse versionnée (/v2/…). Pour un flux XML, et notamment le flux « Site web » qui n'a pas de version dans son adresse, le nouveau format sort sous une nouvelle adresse de flux.

Seule exception : la sécurité. Un changement nécessaire pour corriger une faille ou pour cesser de publier une donnée qui ne devait pas l'être s'applique tout de suite, y compris à une adresse existante. Il est annoncé dès qu'il est en ligne.

Préavis minimum : 6 mois

L'ancienne adresse continue de fonctionner à l'identique pendant au moins 6 mois après l'annonce de sa dépréciation, flux XML compris, hors correctif de sécurité (voir plus haut). Elle n'est retirée qu'ensuite.

Comment une dépréciation est signalée

Une dépréciation est annoncée de quatre façons à la fois :

dans la spécification OpenAPI, l'opération ou le champ porte deprecated: true ;
chaque réponse de l'ancienne adresse porte l'en-tête Deprecation (RFC 9745), la date de dépréciation en secondes Unix précédées de @ ;
elle porte aussi l'en-tête Sunset (RFC 8594), la date de retrait, et un en-tête Link rel="deprecation" qui pointe vers cette page ;
un e-mail est envoyé aux administrateurs des cabinets qui utilisent l'opération.

Exemple d'une opération dépréciée le 1er janvier 2027 et retirée le 1er juillet 2027 :

Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://developers.marvins.ai/docs/versions-et-depreciation>; rel="deprecation"; type="text/html"

État actuel

Aucune opération n'est dépréciée.

Limites de débit

Chaque opération est soumise à un quota de requêtes par fenêtre de temps. Les valeurs dépendent de l'opération et peuvent évoluer : lisez les en-têtes de réponse plutôt que de coder un quota en dur. Les en-têtes RateLimit-Policy et RateLimit suivent le brouillon IETF draft-ietf-httpapi-ratelimit-headers.

En-tête	Contenu
`RateLimit-Policy`	La politique qui s'applique à l'opération : un nom (`"global"` pour la limite commune à l'API, sinon l'`operationId` de l'opération qui a sa propre limite), le quota `q` en requêtes et la fenêtre `w` en secondes. Présent aussi sur un refus d'authentification (`401`).
`RateLimit`	L'état de votre quota pour cette politique : `r` requêtes restantes, `t` secondes avant la fin de la fenêtre. Absent quand la requête est refusée avant d'être décomptée (clé absente, invalide ou sans le droit requis).
`x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset`	Les mêmes informations, sous leurs noms historiques, conservés pour les intégrations existantes.
`Retry-After`	Sur une réponse `429` : le nombre de secondes à attendre avant de réessayer. Il prime sur `RateLimit`.

Exemple de réponse :

RateLimit-Policy: "submitJobApplication";q=30;w=60
RateLimit: "submitJobApplication";r=29;t=60

Les valeurs annoncées sont celles du serveur qui a traité la requête : d'une requête à l'autre, le quota restant peut ne pas décroître de façon régulière. Traitez-les comme une indication, et sur un 429, attendez toujours la durée de Retry-After avant de réessayer, plutôt que de répéter la requête immédiatement.