Recursos · 33
Evolucionar contratos API sin perder clientes
Describir solicitudes, respuestas y errores; probar versiones y hacer que los webhooks sean seguros para reproducir.
Actualizado · 2 min
Lo que esta guía ayuda a lograr
- Redactar el contrato
- Aclarar errores
- Prueba de compatibilidad
- Plan de jubilación
Comprobación rápida
- ¿Qué clientes utilizan cada operación?
- ¿Los errores tienen tipos estables y estados coherentes?
- ¿Un cliente antiguo puede tolerar el cambio?
- ¿Los reintentos pueden duplicar una acción?
- ¿Cómo se anunciará y verificará la baja?
Método paso a paso
- 1
Consumidores de inventario
Listado de operaciones, clientes, usos, versiones y propietarios. Separe el uso observado de los supuestos antes de cambiar un campo.
Entregable: mapa de dependencia del contrato.
- 2
Describir solicitudes y respuestas
Mantener una descripción de OpenAPI con esquemas, ejemplos realistas, respuestas de éxito y fracaso. Compruébelo con el servicio en ejecución.
Entregable: contrato versionado y pruebas de conformidad.
- 3
Errores de estabilización
Utilice estados HTTP según su semántica y, cuando sea útil, un tipo de problema documentado bajo RFC 9457. No exponga secretos en detalle.
Entregable: catálogo de errores probados.
- 4
Clasificar el cambio
Inspeccionar campos obligatorios, tipos, valores, comportamiento, tiempos de espera y paginación. Pruebe los clientes antiguos con la nueva versión con casos representativos.
Entregable: matriz de compatibilidad y decisión de versión.
- 5
Hacer robustas las notificaciones
Para webhooks, autenticación de planes, entrega desordenada, duplicados y reintentos. Haga que el procesamiento sea idempotente cuando sea posible la repetición.
Entregable: escenario de repetición y reconocimiento.
- 6
Liberación con camino de salida
Publicar notas de migración, periodo de convivencia y contactos. Mida el uso de la versión anterior y retírela solo después de verificar a los consumidores afectados.
Entregable: plan de migración y evidencia de retiro.
Indicadores de gestión
| Indicador | Qué mide | Primera acción |
|---|---|---|
| Contrato | Operaciones descritas y comportamiento del servicio coincidente | Arreglar divergencia |
| Compatibilidad | Clientes representativos probados antes del cambio | Añadir casos faltantes |
| Errores | Tipos documentados sin datos sensibles | Revisar mensajes y esquemas |
| Migración | Uso de la versión antigua con un propietario | Asistir a los clientes restantes |
Errores comunes
- Asumir solo un número de versión preserva la compatibilidad
- Documentando solo 200 respuestas
- Devolver un rastro interno o secreto en un error
- Suponiendo que los webhooks lleguen una vez y en orden
Preguntas frecuentes
¿OpenAPI reemplaza las pruebas?
No. Comparar la descripción con respuestas reales y necesidades del consumidor.
¿Cada cambio requiere una nueva versión?
No. Decidir desde el impacto del cliente y el comportamiento del contrato; Los cambios incompatibles necesitan un plan explícito.
¿Por qué errores tipográficos?
Brindan a los clientes una forma estable de distinguir problemas y elegir una acción.
Referencias oficiales
Las referencias respaldan el método. Adapte los controles a su contexto; no constituyen certificación. Los títulos de referencia originales y los documentos fuente pueden estar en otro idioma.
