Una API de datos puede seguir respondiendo con HTTP 200 y haber dejado de servir a quienes la utilizan. Basta con cambiar el significado de un estado, interpretar un importe en otra unidad o devolver resultados en un orden distinto al esperado.
Diseñar un contrato mantenible exige acordar estructura, significado y comportamiento. Una descripción de campos es el comienzo, pero no explica por sí sola cómo debe reaccionar una aplicación ante datos incompletos, actualizaciones concurrentes o una operación pendiente.
Empieza por la necesidad del consumidor
Imagina una aplicación ficticia que consulta entregas para informar a un equipo de operaciones. Su necesidad es conocer qué entregas requieren atención, no acceder a todas las columnas de la base de datos logística.
Un recurso útil podría incluir una identidad estable, el estado operativo, el momento al que corresponde la información y las acciones que admite ese estado. Si la base de datos se reorganiza, el consumidor no debería necesitar conocer el cambio mientras el contrato siga cumpliéndose.
La guía de diseño de APIs de Microsoft recomienda modelar el dominio y evitar que la interfaz sea un reflejo de detalles internos de almacenamiento. Ese criterio puede aplicarse también a una aplicación sin microservicios.
Especifica el significado de cada campo
Para cada dato relevante, responde a cuatro preguntas: qué representa, en qué unidad se expresa, cuándo puede faltar y qué fuente decide su valor.
| Campo ilustrativo | Definición insuficiente | Definición útil |
|---|---|---|
| Estado | Texto | Estado operativo con valores documentados y transiciones permitidas |
| Importe | Número | Importe expresado en una unidad y moneda explícitas |
| Fecha | Fecha de la entrega | Momento del evento identificado, con zona horaria definida |
| Actualizado | Última actualización | Momento en que el sistema de origen confirmó el estado mostrado |
Estos nombres son ilustrativos, no un esquema para copiar sin adaptar. La definición correcta depende del proceso y de sus consumidores.
Diferencia ausencia, error y resultado vacío
Una colección vacía puede significar que no existen entregas que cumplan el filtro. No debería utilizarse para ocultar que el origen no responde. Del mismo modo, un campo nulo no equivale automáticamente a cero o a «no aplicable».
Documenta qué errores puede gestionar el consumidor: entrada inválida, falta de autorización, recurso inexistente, conflicto o indisponibilidad temporal. Acompaña el error con información suficiente para decidir el siguiente paso, sin incluir consultas internas, credenciales o datos de otras empresas.
En operaciones largas, distingue la aceptación de una solicitud de la finalización del trabajo. El cliente necesita consultar un estado verificable, no deducir el éxito porque dejó de recibir mensajes.
Comprueba los cambios que parecen inocuos
Eliminar un campo utilizado rompe el contrato de forma evidente. Hay cambios más sutiles: añadir un nuevo valor a una enumeración, reducir una precisión numérica o modificar el orden predeterminado de una lista.
Antes de publicar una versión, utiliza ejemplos de solicitudes y respuestas que representen consumidores reales. Prueba qué ocurre cuando aparece un campo desconocido y cuando falta un dato opcional. La compatibilidad depende también de cómo estén implementados esos clientes.
Si debes introducir un cambio incompatible, identifica quién utiliza la versión anterior, prepara una transición y define cómo se verificará la migración. Crear una versión nueva sin un plan de retirada puede trasladar el problema a la operación.
Controla las colecciones grandes
La API debe especificar cómo filtra, ordena y pagina. En una colección que cambia mientras se recorre, dos peticiones consecutivas pueden observar estados distintos. Explica qué estabilidad ofrece el recorrido y qué mecanismos tiene el cliente para reconocer duplicados o retomar una lectura.
No prometas una extracción consistente si la implementación no fija un snapshot o una garantía equivalente. Esa limitación puede ser aceptable para una pantalla de seguimiento y resultar inadecuada para una conciliación completa.
Entrega ejemplos que se puedan probar
Un contrato útil incluye solicitudes válidas, casos límite, errores esperados y un responsable de cambios. Conviene convertir sus condiciones importantes en pruebas que se ejecuten cuando cambie el servicio o un consumidor crítico.
En un proyecto de desarrollo web y backend para datos, estos acuerdos reducen discusiones tardías sobre lo que «debería» devolver una integración. Para plantear el diseño a Nexeus Big Data, empieza por describir quién consumirá la información y qué decisión tomará con ella.