Versionado y obsolescencia
Qué puede cambiar sin avisar y qué no.
La versión va en la ruta (/v1/…). Dentro de una versión, Ryde puede hacer cambios retrocompatibles en cualquier momento, y tu integración debe tolerarlos.
| Retrocompatible | Ruptura |
|---|---|
| Un campo nuevo en una respuesta | Eliminar o renombrar un campo |
| Un campo opcional nuevo en la solicitud | Hacer obligatorio un campo opcional |
| Un endpoint nuevo o un alcance nuevo | Eliminar un endpoint o un alcance |
| Un valor nuevo en un enum existente | Cambiar el significado de un valor |
| Un código de error nuevo | Cambiar el estado que devuelve un error |
Analiza con tolerancia: ignora campos que no reconozcas y trata un valor de enum desconocido como algo que no puedes manejar, no como un error. Un cliente que rechaza campos desconocidos se rompe con el próximo cambio aditivo.
Un cambio de ruptura se publica como una versión nueva con anuncio, guía de migración, fecha de obsolescencia y fecha de retirada. Nada en producción se elimina sin esa secuencia.