Versionado

Cada endpoint responde en dos rutas:

POST /api/v1/payments/create     versioned, use this
POST /api/payments/create        unversioned, permanently supported

Hoy ambas ejecutan exactamente el mismo código.

Use la ruta con versión. Es la única forma de tener la certeza de que un cambio futuro no le afectará. Una integración que usa la ruta sin versión recibe aquello a lo que «sin versión» apunte en cada momento, que hoy es v1 y algún día puede no serlo.

La ruta sin versión es un alias permanente, no una funcionalidad obsoleta. No se eliminará. Hay integraciones que no se pueden actualizar, como plugins que los comerciantes actualizan a su propio ritmo o nunca, y esas tienen que seguir funcionando.

Cada respuesta indica qué versión la sirvió:

X-API-Version: v1

GET /api/versions enumera lo que existe y a qué versión se resolvió su solicitud.

Qué cuenta como un cambio incompatible

Avisamos antes de hacer cambios incompatibles. Esa promesa solo tiene sentido si estamos de acuerdo en qué significa el término.

Se publica sin previo aviso, en la versión actual:

• un endpoint nuevo
• un campo de solicitud opcional nuevo
• un campo de respuesta nuevo
• un valor de enum nuevo que se espera que los clientes toleren
• una regla de validación relajada para aceptar más entradas
• una corrección de una respuesta que nunca coincidió con el comportamiento documentado
• cualquier cambio sin efecto visible en las solicitudes o las respuestas

Requiere una versión nueva:

• eliminar o renombrar un campo de solicitud o de respuesta
• cambiar el tipo o el significado de un campo
• cambiar el código de estado de un resultado existente
• hacer obligatorio un campo opcional
• endurecer la validación de modo que se rechacen entradas que antes se aceptaban
• eliminar un endpoint o cambiar su ruta
• cambiar lo que ocurre cuando se omite un campo

La regla de fondo: si una integración que funciona hoy dejara de funcionar, o se comportara de otra manera sin cambiar su propio código, el cambio es incompatible.