La superposición horaria acorta feedback, pero la proximidad no crea significado compartido. Los equipos distribuidos entregan APIs confiables cuando las decisiones se convierten en contratos, ejemplos, tests, ownership y evidencia que sigue clara después de la reunión.
Reserva las horas compartidas para comportamiento ambiguo, tradeoffs, seguridad, incidentes y reviews difíciles. Status, contexto, evidencia y handoffs rutinarios deben ser asíncronos.
La reunión termina con contrato actualizado, decisión, owner, condición de cierre y preguntas. De otro modo el siguiente huso horario repite la conversación.
OpenAPI ofrece contrato independiente del lenguaje. Define auth, operaciones, schemas, ejemplos, errores y entornos. Genera clientes y mocks cuando sirve, con validación runtime y contract tests.
También documenta retries, duplicados, visibilidad, consistencia eventual y campos inmutables. Estas reglas se prueban en CI.
Usa timestamps RFC 3339 con offset y timezone nombrada cuando importa la hora civil. Dinero necesita currency y decimal explícitos. Idioma usa BCP 47 y la visualización bibliotecas CLDR.
No envíes valores formateados ni fechas ambiguas. IDs fiscales, códigos postales, estados, teléfonos, nombres y direcciones son campos de dominio.
El vocabulario técnico compartido ayuda, pero UI, soporte, ejemplos, términos legales y de dominio necesitan review regional. Portugués brasileño, español latinoamericano y supuestos estadounidenses no son equivalentes.
Separa IDs de máquina de labels, almacena locale, usa message catalogs y prueba plural, moneda y fecha.
RFC 9457 define Problem Details. Usa problem type estable, status, title, detalle seguro, referencia, field violations, retryability y códigos. No obligues al consumer a parsear prosa.
Define retry, corrección, reauth, conflict y support. La UI localiza desde códigos estables.
Prefiere cambios aditivos. Remover, cambiar tipos o semántica, exigir campos, alterar defaults o endurecer validación es breaking hasta demostrar lo contrario.
Deprecation tiene owner, reemplazo, telemetry, guía, fecha y rollback. Contract diff y consumer tests bloquean roturas.
El PR incluye problema, contract diff, ejemplos, seguridad/privacidad, migration, tests, evidencia, rollout, rollback, preguntas y decisión exacta.
Usa draft PR temprano, CODEOWNERS y checks requeridos. Mantén PRs pequeños.
Define owners para comportamiento, API, datos, SDK, infra, seguridad, reglas regionales y producción. El owner del repo no necesariamente decide negocio.
Escalamiento sigue impacto y experiencia, no geografía.
CI responde validez de spec, compatibilidad, ejemplos, clients, contract tests, migrations, locales y seguridad antes del review.
Los checks requeridos deben ser deterministas y rápidos; suites lentas pueden correr en paralelo o en staged.
| Artefacto/decisión | Owner | Reviewer | Gate | Falla |
|---|---|---|---|---|
| Lifecycle y edge cases | Producto/dominio. | Operaciones regionales e ingeniería. | Cenarios y state-machine tests. | Equipos implementan significados diferentes. |
| OpenAPI y ejemplos | Provider. | Consumers y seguridad. | Lint, schema, diff y client build. | Mismatches aparecen tarde. |
| Locale, tiempo, dinero e identidad | Dominio/localización. | Representantes EE. UU./PT-BR/ES. | Fixtures de locale, timezone, decimal y dirección. | Código correcto falla regionalmente. |
| Auth y autorización | Seguridad/plataforma. | Provider, consumer, privacidad y operaciones. | Policy tests, negativos, secret scan y threat delta. | Acceso depende de supuestos ocultos. |
| Migration y compatibilidad | Datos/API. | Consumers afectados. | Migration, rollback, diff y old clients. | Release rompe otra región. |
| Release e incident readiness | Service owner. | Soporte, operaciones y stakeholders. | Canary, dashboards, alert test y rollback. | API sale sin responder o evidencia. |
Incluye objetivo, evidencia, PR/branch, entorno, blockers, decisiones, riesgo, owner, próximo paso y expectativa. “Trabajé en el endpoint” no alcanza.
En incidentes: severidad, regiones, inicio, baseline, timeline, hipótesis, cambios, mitigación, comandos, métricas y próximo check.
Mide contrato listo hasta primer éxito, espera de review, change failure, defectos de contrato, rollback, detección/recuperación, reducción de soporte y adopción regional.
Commits, líneas, reuniones y horas online premian visibilidad.
Least privilege en repo, cloud, base y APIs. Credenciales separadas, identidad corta, auditoría, datos de test protegidos y revocación rápida. No compartas secrets de producción en chat.
Define residencia, transferencia, logging y soporte. Usa fixtures saneados y datos sintéticos.
Prueba daylight saving en EE. UU., países sin la misma transición, fin de mes, feriados, UTC, decimales, monedas, acentos, nombres, direcciones, IDs fiscales, teléfonos y errores localizados.
Contract tests corren en provider y consumer; sandbox debe incluir estados reales.
Crearía un template con OpenAPI, JSON Schema, ejemplos, catálogo Problem Details, ADRs, ownership, clients, contract tests, fixtures regionales, CI, release checklist, dashboards, runbook y handoff.
Un portal mostraría owners, consumers, versiones, deprecations, SLOs, cambios, decisiones, sandbox e incidentes.
Nearshore funciona cuando el overlap acelera juicio y los artefactos durables transportan ejecución. No se trata de estar todos online, sino de hacer visibles comportamiento, ownership, evidencia y próximo paso.
Artículo sobre ingeniería nearshore de APIs entre equipos de EE. UU. y América Latina, incluyendo overlap horario, OpenAPI contract-first, localización, tiempo y dinero, review asíncrono, CODEOWNERS, CI, compatibilidad, handoff de incidentes, seguridad, pruebas regionales y métricas.