Revisar desde el cliente
La tabla orienta una revisión, sin garantía universal. Un campo añadido puede afectar a un lector estricto y un valor nuevo de enumeración a una lógica exhaustiva. Inventaríe clientes, bibliotecas y supuestos.
| Cambio | Riesgo | Prueba necesaria |
|---|---|---|
| Eliminar o renombrar un campo | Lectura imposible | Migración explícita y pruebas de clientes. |
| Añadir campo opcional | Lector estricto o conflicto de nombre | Pruebas de consumidores existentes. |
| Añadir valor en respuesta | Lógica exhaustiva incompleta | Tratamiento de valores desconocidos. |
| Cambiar un valor predeterminado | Resultado de negocio distinto | Comparar casos sin valor explícito. |
Planificar la coexistencia
- Describa estructuras anteriores y nuevas, valores predeterminados, errores, paginación y permisos. Ejecute pruebas de contrato con casos representativos.
- Elija una selección explícita de versión. Distinga versión del servicio y del documento OpenAPI; compruebe cachés y pasarelas.
- Publique calendario, guía y contacto. Mida el uso real con telemetría proporcionada y prepare una reversión compatible con los datos.
Separar obsolescencia y cierre
Deprecation señala un recurso obsoleto; Sunset puede anunciar cuándo se espera que deje de estar disponible. Los encabezados no migran clientes. Revise consumidores restantes, obligaciones y recuperación antes de retirar una versión.
Fuentes primarias
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
Versión según el impacto en el consumidor
Agregar un número a una URL no conserva automáticamente los clientes existentes. Un tipo, valor esperado, comportamiento o respuesta de error modificados pueden ser incompatibles incluso si la ruta permanece igual.
- Inventariar los clientes activos y su uso observado.
- Probar versiones anteriores del cliente con el nuevo contrato.
- Publicar un período de coexistencia e inspeccionar el uso antes de su retirada.
Fuente primaria: IETF RFC 9457 — Problem Details for HTTP APIs. Método relacionado: consultar la guía práctica.
Tareas API asíncronas
Una solicitud aceptada no demuestra que el trabajo haya terminado.
- Cuenta, operación e identificador reutilizable
- Estado, hora, intervalo y caducidad
- Resultado, error, cancelación y efectos restantes
- Una tarea autorizada y resultado comprobado tras interrupción
Caso de aceptación reproducible
Ejemplo ficticio: estos datos no describen clientes ni resultados observados.
Ver datos del caso
{
"job_id": "J-42",
"timeline": [
{
"elapsed_seconds": 0,
"http": 202,
"state": "pending"
},
{
"elapsed_seconds": 5,
"http": 200,
"state": "running"
},
{
"elapsed_seconds": 6,
"http": 200,
"state": "cancel_requested"
},
{
"elapsed_seconds": 7,
"http": 200,
"state": "succeeded"
}
]
}Decisión esperada
Un 200 al consultar el estado no significa que el procesamiento terminó. Tras solicitar cancelación, concluir solo a partir del resultado confirmado.
Cancelación solicitada demasiado tarde
Caso ficticio: misma tarea J-42, segundos desde el envío. Los estados pertenecen al contrato del ejemplo; HTTP no los impone.
| Instante | Respuesta y estado | Conclusión justificada |
|---|---|---|
| +0 s | HTTP 202 · pending | Aceptada para procesar; sin resultado final confirmado. |
| +5 s | HTTP 200 · running | La consulta funcionó; la tarea sigue ejecutándose. |
| +6 s | HTTP 200 · cancel_requested | Solicitud de parada registrada; cancelación aún sin confirmar. |
| +7 s | HTTP 200 · succeeded | El procesamiento ganó la carrera. Mostrar el éxito observado y revisar efectos; no indicar cancelación. |
¿202 demuestra que el trabajo terminará?
No. Confirma aceptación para procesamiento, no el resultado final. Consulte el estado de la operación.
Fuente primaria: MDN — 202 Accepted. Método relacionado: consultar la guía práctica.
Actualización de software: verificar un cambio de firmante
Decidir si un artefacto firmado corresponde al productor, proceso y versión aprobados.
- Antes de revisar el paquete, registra productor, clave o identidad del certificado, emisor y proceso de construcción autorizados. Vincula las expectativas al software y a un canal de confirmación ya fiable. El artefacto no debe definir por sí solo su política de aceptación.
- Compara la huella del archivo recibido con el objeto de la atestación. Verifica la firma con las raíces de confianza previstas y después identidad, constructor y parámetros. Una firma válida de otra identidad no cumple la política del servicio.
- Prueba rotación anunciada, emisor inesperado, firma ausente y archivo diferente. Mantén pendiente el artefacto si la nueva identidad no está confirmada. Registra aprobación y alternativa de vuelta; una firma no prueba ausencia de vulnerabilidades.
Caso de aceptación reproducible
Ejemplo ficticio: estos datos no describen clientes ni resultados observados.
Ver datos del caso
{
"signature_valid": true,
"digest_matches": true,
"expected_signer": "approved-publisher",
"observed_signer": "different-publisher",
"expected": "hold_for_independent_confirmation"
}Decisión esperada
Ejemplo ficticio: la huella coincide y la firma es válida, pero el firmante difiere del aprobado. La instalación queda pendiente de confirmación independiente del cambio.
Fuente primaria: SLSA v1.2 — Verifying artifacts. Método relacionado: consultar la guía práctica.
API: obsolescencia y retirada
Las notas detalladas de esta edición están disponibles en inglés.
Plan retirement beyond the version number
A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.
- Distinguish Deprecation, Sunset and policy links.
- Check that Sunset does not precede Deprecation when both dates are provided.
- Measure remaining consumers and validate the replacement before cutover.
Compare deprecation and retirement announcements →
IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23
IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23