Diseño de protocolo primero

Qué es Protocol-first

Protocol-first es un enfoque en el que el contrato de interacción entre componentes (servicios, clientes, socios externos) se diseña y fija antes de la implementación. El código, el almacenamiento, la infraestructura y la documentación están sujetos al contrato y se generan automáticamente a partir de él, no al revés.

A diferencia de «code-first», donde la API es sólo un subproducto del código, Protocol-first hace del protocolo un artefacto primario: posee conceptos de dominio, modelos de datos, estados, errores, semántica de idempotencia, SLO/SLI e incluso una política de versiones.

¿por

Coherencia y previsibilidad de las interfaces en toda la organización.
Acoplamiento rápido (autogeneración SDK/stabs/clientes, errores y códigos uniformes).
Evolución fiable (compatibilidad de circuitos, pruebas de contratos, política de versiones clara).
Enfoque del producto: Discutimos el comportamiento, SLA y integración UX antes de escribir el código.
Automatización: CI/CD recoge artefactos (clientes, enchufes de servidor, validadores) de una sola fuente de verdad.
Seguridad y cumplimiento: derechos, enmascaramiento de PII, políticas de retención están consagrados en el contrato.

Núcleo de enfoque

1. Fuente única de verdad (SSOT): especificaciones legibles por máquina:

REST: OpenAPI/JSON Schema.
Eventos y streaming: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + directivas/políticas.
2. Arreglos previos a la implementación: glosario de dominio, códigos de error, semántica de idempotencia, deduplicación, retraídas, deduplicación.
3. Autogeneración: Stabs de clientes/servidores, tipos, SDK, pruebas de contratos, mocks, colecciones de Postman, configuración de Gateway de Terraform/OpenAPI.
4. Governance: linters/directivas (naming, paginación, filtros, errores), review a través del gremio API, change-advisory para versiones mayores.
5. Compatibilidad: comprobación estricta de diffs «additive-only», versionamiento semántico, pruebas canarias/consumer-driven.
6. Observabilidad a nivel de contrato: identificaciones de correlación, patrones de error, presupuestos de demora se especifican en el protocolo.

Cómo se ve el proceso (esqueleto)

1. Iniciación: resumen de producto → revistas de usuarios → API/Protocolo PRD (recursos/métodos/eventos, SLA/SLO, errores, límites).
2. Modelado: borrador de especificación (OpenAPI/AsyncAPI/Proto) + diagrama de datos, diccionario de términos.
3. Contratos y integración UX: ejemplos de carga útil, contratos de error, mapas de estado, reglas de versionamiento.
4. Rugido y gobierno: linternas/estándares, discusión de invariantes de dominio, lock-in MGC (contrato de garantía mínima).
5. Autogeneración de artefactos: SDK, bandadas, fixtures de prueba, enchufes de infraestructura (Gateways, IAM scopes).
6. Implementación y pruebas de contrato: el proveedor y los consumidores pasan la prueba de compatibilidad en CI.
7. Observabilidad y SLO: rastreo por correlación-id, error catalog, presupuestos de retraídas/timeouts.
8. Lanzamientos y evolución: additive-first, deprecation policy, canary, A/B capability flags.

Protocolos y estilos de interacción

REST/HTTP

Estándares: modelo de recursos, 'GET/POST/PATCH/DELETE', paginación (cursor), filtros, clasificación.
Campos y esquemas: JSON Schema, formatos ('date-time', 'uuid'), invariantes (regex/enum/min-max).
Errores: formato único ('type', 'code', 'title', 'detail', 'trace _ id'), mapping en pilas HTTP.
Control de cambios: ETag/If-Match, llaves idempotentes para POST, semánticas expresas 409/422.

gRPC/RPC

Protobuf: numeración estable de etiquetas, 'optional', prohibición de volver a usar campos remotos.
Deadlines y prioridades en el contrato; estados estables (OK, INVALID_ARGUMENT, FAILED_PRECONDITION, etc.).
Streaming: especificación del orden de los mensajes, backpressure, remolques finales.

Event-driven (Kafka/NATS/SNS/SQS)

AsyncAPI: temas/canales, claves de partición, acuerdos de clave de deduplicación, retenciones, semántica «exactamente una vez» vs «al menos una vez».
Evento-núcleo y enriquecimiento: separe el payload mínimo y las extensiones; versionar 'event _ type '/' schema _ version'.
Idempotencia: 'event _ id', 'producer _ id', política por retrés y deduplicación.

GraphQL

SDL como contrato, directivas para deprechate, límites de profundidad y complejidad, contrato de error (error codes/extensiones).

Integración con principios arquitectónicos

Inverse Pyramid/Critical Path First: en la especificación de resaltar MGC (mínimo obligatorio), las extensiones son a través de '? include = '/capabilities.
Paved Roads: conjunto de plantillas de especificaciones terminadas (payment, KYC, audit, search, files) + linters.
API Gateways & Service Mesh: políticas basadas en contratos (rate-limits, auto-scopes, retries, circuit-breakers).

Versioning y evolución

• Minor = sólo campos/canales aditivos.
• Major = cambios rompedores (eliminar, cambiar el nombre, cambiar la semántica).
• Política de depreciación: ventanas de soporte, encabezados 'Sunset', eventos-notificaciones.
• Contratos de unidad de consumo (CDC): verificamos que la API actual satisface a los consumidores específicos.
• Catálogo de esquemas: Registro (Schema Registry/Artifact Registry) con historial y reglas de compatibilidad (BACKWARD/FORWARD/FULL).

Seguridad y cumplimiento

Autenticación/autorización como parte del contrato (OAuth2/OIDC scopes, mTLS, JWT claims).
PII/PCI: enmascaramiento, formatos de tokenización, campos con modos especiales de almacenamiento/TTL.
Políticas de auditoría: atributos obligatorios ('actor', 'sujeto', 'acción', 'occurred _ at', 'trace _ id').
Límites: rate limit headers, cuotas, tamaños de mensajes, dlines.

Observabilidad contractual

Correlation/Request-ID: obligatorio en la especificación.
Error Catalog: lista fija de códigos y SLA para eliminar.
SLI/SLO: p50/p95 latencia, porcentaje de respuestas exitosas, porcentaje de eventos compatibles, porcentaje de repeticiones idempotentes.

Pruebas y calidad

Pruebas de contrato (proveedor ↔ consumidor), schema diff en CI, generación de servidores moc.
Ejemplos de oro: ejemplos de referencia de consultas/respuestas, fixtures para e2e.
Inyección de chaos/latencia: validación de temporizadores/retraídos, degradación de extensiones mientras se guarda el MGC.

Plantillas de dominio de ejemplo

Pago (NAT + eventos)

'POST/payments' (clave idempotente) → '201 Created' con 'payment _ id', 'status = authorized'.
Evento 'payment. authorized. v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.
Extensión 'payment. enriched. v1 ': riesgo-score, geo, device-fingerprint.
Errores: '422' (validación), '402' (pago requerido), '409' (duplicado).
SLA: autorización ≤ 800ms p95; evento de kernel ≤ 2s lag p95.

KYC (gRPC + colas)

RPC `StartVerification(user_id)` → `operation_id`.
Acontecimientos de progreso en el topic 'kyc. status. v1` (`PENDING` → `APPROVED/REJECTED`).
El contrato estipula los campos PII, la vida útil, el enmascaramiento, los códigos causales del fracaso.

Auditoría

`audit. recorded. v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.
Enriquecimiento: IP, device, geo - evento/flujo individual, no bloquea el núcleo.

Herramientas y automatización (pila de ejemplo)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
Gateway: Kong/Apigee/Azure/GCP GW, Envoy.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Registro: Directorio git de esquemas + Registro de Schema/Registro de artefactos.
Documentación: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Anti-patrones

Code-first by accident: «primero MVP en los controladores», especificación post-factum, documentación divergente y comportamiento.
Swagger-wash: OpenAPI formal sin reglas reales (errores, límites, SLA, versiones).
Capa de compatibilidad: eliminó el campo/cambió el tipo sin la versión mayor; reutilización de etiquetas protobuf.
Respuesta «gruesa» sin paginación/filtros; falta de idempotencia.
Securities fuera de contrato: auth/Scopes se describen en wiki, pero no en especificación.

Relación con la organización del proceso

API Guild: cuidadores de estándares, rugidos de cambios, aprendizaje.
Documentos de diseño: por cada API - PRD, ADR (soluciones), SLA, matriz de riesgo.
Change Management: proceso RFC, notas de release, gaids de migración, tiempo de entrega.
Paved Road & Templates: generadores de esqueletos de servicio a partir de especificaciones (esqueleto de handlers, validación, lógica).

Hojas de comprobación

Antes

• Hay un PRD y un glosario de dominio.
• Se ha seleccionado un estilo (NAT/gRPC/Event/GraphQL) y un formato de esquema.
• Definidos MGC, errores, SLA/SLO, reglas de idempotencia.

• La especificación pasa los linderos y review.
• La generación automática de SDK/Stabs/Fixtures está configurada.
• Las pruebas de contrato (CDC) se incluyen en el CI; schema-diff bloquea los cambios incompatibles.

Antes

• Documentación para integradores con ejemplos y códigos de error.
• Observabilidad contractual: correlation-id, error catalog, dashboards SLI.
• Política de versionabilidad y deprecación declarada.

FAQ

¿En qué se diferencia Protocol-first de la API-first?
A menudo, los términos se usan como sinónimos. En este artículo bajo Protocol-first destacamos el rigor del contrato y la cobertura de todos los estilos (NAT/RPC/Events/GraphQL), incluyendo SLA, seguridad y observabilidad.

¿Esto ralentizará el desarrollo?
El inicio puede ser un poco más largo, pero luego ganamos en integraciones, estabilidad y velocidades de desarrollo paralelo (autogeneración, SDK estables).

¿Qué hacer con los experimentos rápidos?
Utilice las versiones «borrador» de diagramas (draft), flags de características y sandbox, pero no deje pasar las reglas de linterna y compatibilidad básicas.

El diseño protocol-first hace del contrato el centro de la arquitectura: conciliamos el comportamiento, fijamos los circuitos, automatizamos la generación y las pruebas, evolucionamos aditivamente. Como resultado, obtenemos integraciones predecibles, alta velocidad de desarrollo y resiliencia de los sistemas a los cambios de escala y de equipo.