Estrategias de versificación de API

¿Por qué necesitas versionar?

La API cambia más rápido que los clientes. La versionización permite liberar fiches y gobernar errores sin roturas de integraciones, establece un ritual de cambio y hace predecible la evolución. Clave: cambios aditivos predeterminados, majors - sólo para roturas, comprobaciones automáticas de compatibilidad y una política de sunset bien pensada.

Principios básicos

1. Additive-first: nuevos campos/métodos/eventos opcionales - aprox; eliminación y cambio de sentido - mayor.
2. MGC (contrato de garantía mínima) es estable; enriquecimiento - a través de capabilities/'? include = '.
3. Lector tolerante: los clientes ignoran campos desconocidos y sobreviven correctamente a las extensiones enum.
4. Semantic Versioning: `MAJOR. MINOR. PATCH 'para artefactos, SDK y eventos.
5. Automate: schema-diff, linters y pruebas de CDC bloquean los cambios de breaking.

Dónde almacenar la versión (mecánicas de direccionamiento)

REST/HTTP

Versión URI: '/v1/orders '→ simplemente enrutar, convenientemente en gateways. Menos - «oscurece» la evolución de las representaciones.
Mediatip/título: 'Accept: application/vnd. example. orders. v1 + json '- control preciso del formato; es más difícil debilitar.
Versión Query: '? api-version = 1' - conveniente para A/B, pero fácil de perder en cachés/logs.
Recomendación: URI para líneas major + flags de características/capability y contenido de no activación para extensiones menores.

gRPC / Protobuf

Paquetes/servicios: 'package payments. v1; PaymentsV1; '- líneas explícitas.
La numeración de etiquetas no cambia; no se pueden volver a utilizar las etiquetas eliminadas.
Los nuevos campos son 'optional'; breaking → nuevo '.v2'.

GraphQL

Esquema sin mayor explícito en la URL. Evolución a través de @ deprecated y ventanas de migración; El «verdadero» mayor es un nuevo circuito endpoint.
Controlar complexity/depth es parte del contrato.

Event-driven (Kafka/NATS/Pulsar)

Nombre del evento: 'pago. authorized. v1 'es la versión del tipo.
Registro de circuitos (Avro/JSON Schema/Protobuf) con modos de compatibilidad (BACKWARD/FORWARD/FULL).
Mayor → dual-emit 'v1' y 'v2' para el período de transición.

Modelo de versión y política de cambios

Semantic Versioning

MAJOR - cambios rompedores: eliminar/cambiar el nombre de los campos, cambiar las claves de partición, diferente significado de los estados, apretar la validación.
MINOR - aditivo: nuevos campos opcionales/endpoints/eventos, nuevos valores enum en tolerant-reader.
PATCH - correcciones sin cambios en el contrato y la semántica.

Deprecation & Sunset

Marca lo obsoleto ('Deprecated: true', '@ deprecated'), publica sunset-date, alternativa y hyde de migración.
En HTTP, los encabezados son 'Sunset', 'Deprecation'; en eventos - individual '.deprecation. notice`.
Mantener la telemetría usage para tomar una decisión de retirada.

Estrategias de versión por estilo

REST

Grandes líneas en/v1 ,/v2.
MINOR: extensión de circuitos, '? fields =', '? include ='; extensiones enum seguras.
ETag/If-Match y POST idempotentes para una consistencia sin roturas.
Errores - formato estable ('type', 'code', 'trace _ id').

gRPC

Introduce nuevos servicios/métodos para romper: 'PaymentsV2. Capture`.
Los estados de error y la semántica deadline son parte del contrato; cambio → nuevo método/servicio.
Streaming: negocia el orden de los mensajes y no lo cambies en minor.

GraphQL

Agregue campos y tipos libremente; desinstalación: a través de la ventana de migración '@ deprecated' +; un gran rediseño → un nuevo esquema ('/graphql-v2 ').
Introspección y descripciones - must-have para migraciones de clientes.

Events

Core vs enriched: el núcleo es estable, el enriquecimiento vive cerca y se versiona por separado.
La clave de lote no se modifica dentro de la línea mayor.
Mayor-migración - 'dual-emit' + migración de proyecciones/consumers.

Negotiation y capability-flags

Capabilities: el cliente envía 'X-Capabilities: risk_score,price_v2'; el servidor responde con una vista avanzada.
Prefer (HTTP) y "hints' para respuestas parciales.
En sockets/streams, un mensaje handshake con una lista de extensiones admitidas.

Lanzamiento de versiones mayores sin dolor

1. RFC/ADR: por qué se necesita un mayor, qué se rompe, una matriz de riesgo.
2. Dual-run: ejecución paralela de 'v1' y 'v2' (doble publicación de eventos, dos gateway-routs, duplicación de tráfico).
3. Adaptadores de migración: proxy/traductores 'v1↔v2' para clientes pesados.
4. Canario: por grupos de clientes/topics/etiquetas en gateway.
5. Plan Sunset: fechas, comunicaciones, stands, datos de prueba, monitoreo de uso.

Roles de plataforma e infraestructura

API Gateway/Service Mesh: enrutamiento por versión, encabezados, paths; rate-limit и auth per-version.
Schema Registry & Catalog: la fuente de la verdad para el spec/circuitos con la historia de los diffs.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observabilidad: la versión debe estar en los logs/tracks/métricas.

Pruebas de versiones

Schema-diff en PR: bloquear el breaking.
Contratos Consumer-Driven: el proveedor se verifica contra los contratos de los consumidores reales.
Muestras de oro: respuestas de referencia a las versiones.
E2E-canario: comparación de p95/p99, errores y temporizaciones entre versiones.
Replay para eventos: las proyecciones se superponen a v2 sin discrepancias.

Migración de datos y bases de datos

Para NAT/gRPC: las migraciones de DB se coordinan a través de expand-and-contract (agregue una columna → comience a escribir → cambie de lectura → golpee el viejo).
Para Eventos: dual-emit y migración de consumers; a veces - reprueba el registro para nuevas proyecciones.
No haga «grandes explosiones» - aplastar en los pasos de retroceso.

Relación con la seguridad

Scopes per version: roles/OIDC separados para v1/v2.
Los secretos/claim's del token son parte del contrato; su cambio = mayor.
PII/PCI: no amplíe el payload sin necesidad; nuevos campos - con un mínimo de privilegios.

antipatterny

Swagger-wash: la especificación está actualizada, el servidor no (o viceversa).
Volver a usar las etiquetas protobuf es un deterioro silencioso de los datos.
Cambio de sentido enum sin mayor.
Global '/v2 '«por el bien de los cosméticos»: una versión sin el hecho de romper.
Se han olvidado las métricas de sunset/usage: no es posible quitar la versión anterior de forma segura.
Un topic común para diferentes mayores: la mezcla de órdenes y claves.

Lista de comprobación antes de su lanzamiento

• Los cambios son aditivos o se ha preparado una línea mayor separada.
• Linters y schema-diff verde (breaking no derramó).
• SDK/ejemplos/documentación actualizada, notas de pie de página sobre compatibilidad.
• Se incluye un lector de tolerantes en los clientes; enum-fallback probado.
• Para mayor - plan dual-run, adaptadores, canario, sunset-dates y boletín.
• Métricas/logs/tracks contienen la versión y la segmentación a lo largo de ella.
• Hay un stand y kits de oro para comparar v1↔v2.
• Para eventos - el registro de esquemas en el modo BACKWARD/FULL, las claves de lote no cambian.

Plantillas de ejemplo

REST (URI + negotiation)

Ruta: '/api/v2/orders/{ id} '

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment. captured. v2 '(núcleo) y' payment. enriched. v2 '(piezas).
Para el periodo de transición del productor van 'v1' y 'v2'.

FAQ

¿Cuándo se necesita exactamente '/v2 '?
Cuando cambian los invariantes/semánticas, se eliminan los campos/métodos, cambia el formato de los identificadores, la clave de partición, los SLA/timings para que los clientes se rompan.

¿Se puede vivir sin una versión explícita en NAT?
Sólo para sistemas pequeños. Para integraciones externas - mejores líneas mayores explícitas.

¿Cuál es el plazo para mantener una versión obsoleta?
Depende del ecosistema. Para los socios externos, normalmente de 6 a 12 meses con notificación temprana y canario.

¿En qué difiere la versificación de eventos de la API?
Eventos - append-only; nueva semántica = nuevo tipo '.v2' y dual-emit. La clave del partido es parte del contrato.

Resultado

Las estrategias de versionamiento son el proceso y las herramientas: evolución aditiva por defecto, líneas mayores claras, capability-negotiation, dual-run y sunset. Agregue comprobaciones automáticas de compatibilidad, telemetría de uso y disciplina de documentación a esto, y sus API se desarrollarán rápidamente, sin «migraciones nocturnas» y caídas inesperadas en los clientes.