Versionado y obsolescencia

La v1 queda congelada en la disponibilidad general

A partir de la disponibilidad general (GA), /api/v1 solo cambia de forma aditiva:

operaciones nuevas;
miembros opcionales nuevos en los cuerpos de las peticiones, parámetros de consulta opcionales nuevos;
miembros nuevos en las respuestas;
valores nuevos de enumeraciones en las respuestas;
códigos de error nuevos para situaciones nuevas.

Nada de lo que funciona hoy se elimina, se renombra ni cambia de significado dentro de la v1. Hasta la disponibilidad general la API todavía puede cambiar; cada cambio de ese tipo figura en el registro de cambios.

Lo que debe hacer tu cliente

Para seguir siendo compatible con los cambios aditivos, un cliente debe:

ignorar los miembros desconocidos de las respuestas (no fallar por ellos ni rechazar el objeto);
aceptar valores de enumeración desconocidos (tratar un status desconocido como «otra cosa», no como un error);
no depender del orden de los miembros ni de los elementos, salvo donde la referencia diga que el orden está definido;
decidir en función del code del error, no del texto para personas.

Las bibliotecas cliente y la CLI ya se comportan así.

Obsolescencia

Cuando algo tiene que desaparecer, primero se declara obsoleto:

la operación se marca como deprecated en la referencia, con la fecha a partir de la cual se puede retirar (x-pluspanel-sunset);
sus respuestas llevan la cabecera Deprecation (RFC 9745) y la cabecera Sunset (RFC 8594) con esa fecha, además de un Link a esta página con rel="deprecation";
el registro de cambios la menciona, junto con lo que la sustituye.

La fecha de retirada es al menos 12 meses posterior al anuncio:

HTTP/1.1 200 OK
Deprecation: @1792368000
Sunset: Thu, 19 Oct 2028 00:00:00 GMT
Link: <https://pluspanel.net/docs/api/versioning/>; rel="deprecation"; type="text/html"

Registra estas cabeceras en tus logs cuando aparezcan, para que una obsolescencia nunca te pille por sorpresa.

Una nueva versión mayor

Las retiradas solo ocurren en una nueva versión mayor, /api/v2. Cuando llegue la v2, la v1 seguirá funcionando a su lado al menos 12 meses, para que migres a tu ritmo. Las mismas claves de API sirven para ambas.

Webhooks

Los payloads de los webhooks siguen las mismas reglas: pueden aparecer en cualquier momento tipos de evento nuevos y miembros nuevos en data; los receptores deben ignorar lo que no conocen.