Versions i compatibilitat

L’API té una única versió major, /v1, i només creix. Una integració escrita avui continua funcionant a mesura que arriben funcions noves: res del que fa servir es reanomena, s’elimina ni rep un significat nou.

El número de versió

L’API té un número de versió com ara 1.62.0. Canvia amb cada publicació:

• el número de versió menor, quan s’afegeix alguna cosa: un punt final, un camp, un esdeveniment;
• el número de pedaç, quan es corregeix una descripció o el text d’un missatge i no canvia res més.

Podeu consultar en qualsevol moment la versió que serveix una adreça:

GET /v1/health també té un version, però és la versió de la publicació de Sursa que serveix l’adreça, no la versió de l’API.

No trieu la versió menor: totes les sol·licituds les serveix la versió actual. Gràcies a les regles següents, això no comporta cap risc.

Què pot canviar a /v1

Aquests canvis poden arribar en qualsevol versió menor. Escriviu la integració de manera que no la trenquin:

• Punts finals nous.
• Paràmetres i camps de sol·licitud nous opcionals. Les sol·licituds que no els porten es comporten com abans.
• Camps nous a les respostes, als objectes i als esdeveniments.
• Valors nous d’enumeracions a les respostes, com ara un estat d’entrada nou o un tipus d’esdeveniment nou.
• Codis d’error nous i capçaleres de resposta noves.
• Límits que esdevenen menys estrictes: una longitud màxima més gran, un interval més ampli.
• Textos message dels errors i descripcions amb una redacció nova.

Què ha de tolerar el vostre codi

• Ignoreu els camps que no conegueu. El codi no ha de fallar quan una resposta té més camps dels que espereu, i no feu servir esquemes estrictes que els rebutgin.
• Accepteu els valors d’enumeració que no conegueu. Qualsevol enumeració d’una resposta pot créixer. Tracteu un valor desconegut com a «altre» i no com un error.
• Ometeu els tipus d’esdeveniment que no conegueu, tant als webhooks com als fluxos.
• Gestioneu els codis d’error desconeguts segons el seu estat HTTP: vegeu Errors.
• No depengueu de l’ordre dels camps dels objectes JSON ni del text exacte dels missatges.

Què no canvia mai a /v1

• Un camí, un paràmetre, un camp o un valor d’enumeració no es reanomena ni s’elimina mai.
• El tipus d’un camp no canvia mai, i un camp no adquireix mai un significat nou, com ara unes unitats noves.
• Una sol·licitud que s’accepta avui no es rebutjarà més endavant.
• El codi d’estat d’una resposta correcta es manté igual.
• Els codis d’error conserven el seu significat, i el camp detail de les respostes d’error conserva la seva forma.
• Els tipus d’esdeveniment no es reanomenen ni s’eliminen mai, i el seu data només guanya camps.

Canvis incompatibles

Si mai cal un canvi incompatible, es publica com una versió major nova, com ara /v2, al costat de /v1. /v1 continua funcionant sense canvis, i totes dues versions funcionen en paral·lel.

Quan s’ha de retirar una ruta:

1. Es marca com a deprecated a l’especificació i apareix al registre de canvis amb la data en què es desactivarà.
2. Les seves respostes porten les capçaleres Deprecation: true i Sunset: <date>.
3. Continua funcionant com a mínim 180 dies després de l’anunci. Les organitzacions amb claus d’API que la fan servir en reben avís per escrit com a mínim 90 dies abans.
4. Després de la data de retirada, respon 410 amb el codi api.gone durant 90 dies més.

Vigileu la capçalera Deprecation als vostres registres o al monitoratge: és el primer senyal que una ruta que feu servir desapareixerà.

Estar al dia

El registre de canvis d’aquest portal enumera cada publicació amb el que s’hi ha afegit i el que s’ha declarat obsolet. Abans d’actualitzar la vostra integració, compareu-ne el codi amb les anotacions publicades des de la versió amb què la vau construir.