Versionado de la API
La versión va en la ruta: /api/v1. Dentro de v1 solo se añade; lo que rompe va a v2.
Qué puede cambiar sin aviso dentro de v1
Tu cliente debe tolerar todo esto desde el primer día:
- Propiedades nuevas en cualquier objeto de respuesta o de webhook.
- Valores nuevos en enumeraciones: estados, canales, categorías de vehículo, tipos de evento, códigos de error, scopes.
- Endpoints, parámetros de consulta y campos de cuerpo opcionales nuevos.
- El texto de
error.message. - El orden de las propiedades y el formato interno de los cursores.
Qué no cambia dentro de v1
- Quitar o renombrar una propiedad, un endpoint, un parámetro o un valor de enumeración existente.
- Cambiar el tipo de una propiedad o convertir en obligatorio lo que era opcional.
- Cambiar el formato del error, de la paginación o de la firma de los webhooks (
version: 1en el cuerpo). - Exigir un scope nuevo para algo que ya funcionaba con los actuales.
| Cambio | Dónde se anuncia | Qué haces |
|---|---|---|
| Aditivo (compatible) | Changelog | Nada. Ignora lo que no conozcas. |
| Ruptura | Nueva versión /api/v2 + changelog + aviso a cada integración | Migras cuando quieras dentro del plazo de retirada de v1. |
| Retirada de una versión | Changelog y cabeceras Deprecation / Sunset en las respuestas de esa versión | Migras antes de la fecha de Sunset. |
Cuando una versión entre en retirada, sus respuestas llevarán Deprecation: true y Sunset: <fecha HTTP>, y el changelog dirá la fecha. El plazo mínimo de aviso se publicará en el changelog antes de que haga falta por primera vez. Hoy solo existe v1 y no hay ninguna retirada prevista.
Versión del cuerpo de los webhooks
Cada webhook lleva version y hoy siempre vale 1: no hay forma de pedir otra, ni por endpoint ni por integración. Existe para que puedas comprobarla antes de parsear y para que el día que cambie la forma del cuerpo te enteres por el propio cuerpo. Cómo se hará esa transición —si se fija por endpoint o se anuncia con plazo para todos— se publicará en el changelog antes de que haya una version: 2, no ahora.
El contrato como fichero
/openapi.yaml es la descripción OpenAPI 3.1 de v1. Cada operación lleva x-scopes con los scopes que exige. Está validado contra el código en cada cambio: si generas un cliente a partir de él, genera también tus pruebas.