Debido a que los servicios se despliegan de forma independiente, nunca puedes asumir que los llamadores se actualizan en sincronía. Versionamiento de API más compatibilidad hacia atrás permite que los productores evolucionen sin romper a los consumidores existentes.
| Estrategia | Ejemplo |
|---|
| ruta URI | GET /v2/orders/42 |
| encabezado | Accept: application/vnd.api.v2+json |
| evolución de esquema | agregar campos, nunca remover/renombrar |
NON-BREAKING (safe):
✓ add a new optional field
✓ add a new endpoint
✓ add a new enum value (if clients tolerate unknowns)
BREAKING (needs a new version):
✗ remove or rename a field
✗ change a type or make a field required
✗ change semantics of an existing field
message Order {
string id = 1;
double total = 2;
string currency = 3; // NEW field 3 — old clients ignore it safely
}
Los números de campo, no los nombres, definen el formato de transmisión, por lo que agregar campos es compatible hacia atrás.
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
Nunca elimines una versión mientras haya tráfico real que la use. Rastrea el uso antes de retirar.
La implementabilidad independiente solo funciona si un productor puede enviar un cambio sin coordinar el lanzamiento de cada consumidor.
Diseñar para cambios aditivos y soportar versiones antiguas durante la migración es lo que preserva esa independencia en lugar de forzar actualizaciones frágiles de gran envergadura.