Tecnologías e Infraestructura → Versificación de API

Versificación de API

1) Por qué es necesario

• reduce el riesgo de incidentes en lanzamientos,
• permite introducir mejoras y seguridad de forma planificada,
• proporciona al negocio plazos predecibles para las migraciones de socios.

2) Clasificación de cambios

PATCH (no rompiendo): correcciones sin modificar el contrato (agregando campos opcionales, fijos de validación).
MINOR (extensibles): extensiones back-compatible (nuevos endpoints, campos con default).
MAJOR (rompiendo): cambio de estructura, semántica o eliminación de campos/endpoints.

Se recomienda SemVer 'MAJOR. MINOR. PATCH 'para artefactos (SDK/diagramas), con un número de API «externo» que se puede simplificar (v1, v2).

3) Modelos de versionamiento NAT

1. EN URI:

`GET /v1/payments/{id}`

Ventajas: transparente, en caché, fácil de enrutar. Contras: duplicación de documentación, más difícil de evolucionar sutilmente.

2. En encabezados (content negotiation):

`Accept: application/vnd. company. payments. v2+json`

Pros: flexibilidad, ausencia de «basura» en la URL, evolución cómoda del mediatip. Contras: es más difícil de cargar en el navegador, necesita un cliente disciplinado.

3. En el encabezado personalizado:

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

Pros: sólo en la pasarela. Contras: no hay estándar, cuidado con la caché.

4. Versión-fecha (fecha-base):

Bueno para fintech/reporting: «cortes» predecibles de cambios (por ejemplo, trimestrales).

5. Versificación de recursos/modelos:

Recomendación: para integraciones externas - 'URI vN' + Deprecation/Sunset encabezados; para el interior: puede Aceptar o encabezar la versión si la puerta de enlace y la plataforma lo admiten.

4) GraphQL

Preferencia - sin versiones globales. Evolución a través de la adición de campos/tipos y despricación ('@ deprecated (reason: «»...)').
Los cambios rompedores son sólo en ventanas «grandes» (versioned schema namespace) con gaida migratoria.
Tenga en cuenta «n + 1» y no cambie el meaning de los campos existentes.

5) gRPC / Protobuf

Los números de campo son inmutables. Los campos eliminados se marcan como 'reservado'.
Agregue los campos como optional con default seguro.
Utilice buf breaking/lint para verificar automáticamente la compatibilidad.
Versione los paquetes/módulos: 'package payments. v1;` → `payments. v2`.

6) API de eventos (EDA)

El esquema de eventos es el mismo contrato. Almacenarlo en el Registro de Schema (Avro/JSON-Schema/Protobuf).
Topics y versiones: 'payments. v1. authorized`, `payments. v2. authorized`.
Cambios rompedores: un nuevo tipo de evento o un nuevo topic.
Garantía de evolución: backward-compatible para los consumeros durante el período LTS.

7) Política de desproporción y EOL

• Depreción: etiquetas en el changelog y en las especificaciones (OpenAPI/GraphQL SDL), título
• 'Deprecation: true' y siempre que sea posible 'Sunset: Tue, 31 Mar 2026 00:00:00 GMT'.
• Comunicaciones: email/portal de socios, webhooks-notificaciones, notas release.
• Plazos: MENOR - 3-6 meses de soporte, MAYOR - 9-18 meses (depende de la criticidad).
• Ventanas temporales: fijar en la «Política de versionamiento de API».

8) Enrutamiento y versiones

API Gateway (Kong/Apigee/Nginx/Envoy): reglas por prefijo '/v1/', por título o mediatipo.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: rueda la nueva versión al 1-5% del tráfico, compara métricas y registros de errores contractuales.
Flagelos de características: ocultamos el comportamiento sin cambiar el contrato.
Migración zero-downtime: con MAJOR, proporcione doble escritura/lectura (dual-write/read) del esquema de datos.

9) Pruebas contractuales y control de compatibilidad

OpenAPI Diff (o swagger-diff): compruebe que MINOR/PATCH no rompa los esquemas.
Spectral linting - estilo, metadatos obligatorios (versión, Deprecation).
Contratos de controladores de consumo: garantiza que el proveedor no rompa a los clientes.
buf breaking для protobuf.
El CI debe caer en cambios rompedores sin aumentar el MAJOR.

10) Documentación y SDK

Versione los sinterios: '/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
Generar SDK por versión (npm/maven/pypi) con SemVer y changelog.
Marque los métodos heredados en SDK con anotaciones/Deprecated.

11) Observabilidad por versión

• RPS/latencia/errores por versión (etiqueta 'api _ version').
• Mapas de uso de endpoints: ¿quién más en v1?
• Alertas: «> 10% 4xx due to contract mismatch», «clientes antiguos> X% después de la fecha T».

12) Versión y almacenamiento en caché

La versión en ruta mejora la capacidad de almacenamiento en caché de CDN.

• `Vary: Accept, X-API-Version`.
• No cambie la semántica de respuesta en MINOR para romper las claves de caché.

13) Seguridad

No cifrar ni coser la versión en JWT: la versión define la solicitud en lugar de la señal.
No revele los números de ensamblaje internos. En los mensajes externos, utilice «v1/v2».
Con MAJOR, revise la validación, los límites, el enmascaramiento PII.

14) Migraciones y ayudantes automáticos

Publique «Guía de migración v1 → v2»: tabla de coincidencias de campos, ejemplos de consultas/respuestas, casos edge.
Ofrece linternas para clientes (CLI) que resaltarán campos obsoletos.
Para los socios más grandes, una caja de sandbox con dos versiones y un dataset de prueba.

15) Anti-patrones

«Eterno v1»: ausencia de desdlines y métricas de uso.
Cambios de ruptura ocultos en MINOR/PATCH.
«Version in query string» ('? v = 2') - rompe la caché y la legibilidad.
«Un endpoint - cien valores de bandera»: difícil de probar/documentar.

16) Lista de verificación de implementación

1. Modelo seleccionado (URI/Accept/Header) para clientes externos e internos.
2. SemVer para especificaciones y SDK, un cheque automático en CI.
3. Deprecation/Sunset directivas y plantillas de comunicación.
4. Gateway-routing + canarios, dashboards por versiones.
5. Pruebas de CDC/Contrato para integraciones críticas (pagos, KYC, informes).
6. Documentación/SDK/guía migratoria publicada al mismo tiempo que el lanzamiento.
7. Plan EOL con fechas y responsables.

17) Ejemplos

17. 1 NAT (URI + encabezados)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 Content Negotiation (mediatip)

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (Despricación del campo)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 Modelo de eventos

• `wallet. v1. balance. updated`
• `wallet. v2. balance. changed '(nuevo evento con esquema avanzado)

Los esquemas se almacenan en el Registro, la productora no publica eventos con un esquema que rompa la compatibilidad.

18) Contexto iGaming/Fintech (práctica)

Pagos: entrada v2 para nuevos PSPs donde 'status '/' decline _ reason' se amplían; en la puerta de enlace mapping v1 → v2 para informar.
KYC: MINOR agrega el campo 'pep _ screening', los clientes v1 ignoran, v2 - requiere.
Juegos/límites responsables: MAJOR cambia el modelo de límites (dietas/semanas). Doble exportación a informes hasta EOL v1.
Informes a reguladores: versiones fijas-fechas: 'reporting-2025-01'.

19) Mini-política (ejemplo para wiki)

Modelo: para APIs externas - 'URI/vN/'; para internos - 'Accept:... vN + json' o'X-API-Version: N'.
SemVer: las especificaciones y SDK se publican como 'N. minor. patch`. MAJOR requiere RFC/ADR.
Compatibilidad: MINOR/PATCH - sin cambios rompedores. Rompiendo → sólo a través de MAJOR.
Deprecation/EOL: anuncio con ≥90 días de antelación; Sunset-date en los encabezados; Rama LTS para clientes críticos.
Control: OpenAPI diff/buf breaking en CI, CDC para integraciones clave.
Observabilidad: métricas/registros con la etiqueta 'api _ version'.
Lanzamientos: canario 5% ≥ 24h, luego paso a paso hasta 100% con métricas verdes.

Resultado

La versificación no es pro «/v2 en la URL », sino sobre el proceso: reglas explícitas de evolución, verificaciones automáticas de compatibilidad, lanzamientos gestionados y respeto a las integraciones. Introduzca una política clara, automatice el control y la observabilidad, y los cambios dejarán de ser una amenaza para el producto.