Imagine que un sitio de pedidos envía un nuevo pedido a un sistema de gestión operativa. El sistema lo guarda, pero la confirmación nunca llega al sitio web. ¿Debe el sitio intentarlo de nuevo? ¿Podría crear un segundo pedido? Esta situación ilustrativa muestra por qué un contrato de API importa para las operaciones del negocio. Describe el comportamiento esperado en ambos extremos, incluidos los casos que una demostración exitosa quizá nunca revele.
En esta página
Empiece por el recorrido de negocio y la responsabilidad sobre los datos
Trace una interacción desde la acción del usuario hasta su resultado confirmado. En el ejemplo del pedido, identifique quién crea la referencia, qué sistema decide si se acepta y dónde consulta el cliente su estado. Distinga entre recibir una solicitud y aceptar un pedido: pueden ser eventos diferentes. Decida también qué sistema puede modificar cada dato. Si ambos pueden editar una dirección de entrega, el contrato necesita una regla para gestionar las actualizaciones, en lugar de suponer que la última pantalla contiene el valor autorizado.
- Identifique al responsable de la información de pedidos, clientes y estados.
- Especifique qué resultado debe ver el usuario de inmediato.
- Identifique las actualizaciones posteriores que debe enviar el sistema receptor.
Concrete las definiciones de los campos
Para cada mensaje, documente la información obligatoria, los valores permitidos y el significado de los datos ausentes. Un precio necesita una moneda y una interpretación clara; una marca de tiempo, una convención de zona horaria acordada. Utilice un pedido de ejemplo realista para analizar estas reglas. Pregunte si «cancelado» describe todo el pedido o un solo artículo y si una dirección vacía significa que se desconoce o que se ha eliminado deliberadamente. Describa qué registros puede leer o cambiar cada cliente de la API. Estas decisiones afectan tanto a la especificación como a la experiencia de uso; hacer coincidir los nombres de los campos no basta para resolverlas.
Especifique las solicitudes repetidas y los errores útiles
Para el pedido del ejemplo, una regla propuesta podría ser: durante un periodo de conservación acordado, reenviar el mismo identificador de solicitud con los mismos datos del pedido devuelve la referencia existente. Reutilizar ese identificador con otros datos genera un conflicto que debe resolver quien llama a la API. Defina expresamente el ámbito del identificador y su periodo de conservación. Después, distinga los errores que requieren corrección de los fallos temporales. Un tiempo de espera agotado no demuestra por sí solo si el pedido se guardó, por lo que el cliente de la API necesita comprobar el resultado antes de decidir el siguiente paso.
- Falta la dirección de entrega: devuelva una explicación a nivel de campo; corrija la solicitud antes de reenviarla.
- Resultado incierto: consulte el identificador de solicitud y contraste su estado registrado.
- Fallo temporal del servicio: siga la política de reintentos acordada; evite crear una nueva identidad de pedido en cada intento.
Acuerde cómo probar y modificar el contrato
Pida a ambos equipos que recorran un pedido correcto, una solicitud repetida, una dirección no válida y una confirmación interrumpida. Compruebe que esperan el mismo resultado en cada caso. Conserve estos ejemplos junto a la especificación y utilícelos cuando cambie la integración. Identifique a los responsables de aprobar cambios, avisar a los equipos conectados e investigar incidencias. La entrega debe explicar cómo puede el soporte rastrear una solicitud sin exponer información innecesaria del cliente y cómo se introducirá un cambio incompatible para los consumidores actuales de la API.