Una API es simplemente la forma en que una pieza de software le pide algo a otra. Su tienda en línea le pregunta a su sistema de inventario cuántas unidades quedan. Su software de contabilidad le pide al banco las transacciones de hoy. Un escáner de almacén le dice al sistema principal que un palé acaba de enviarse.
Estas conexiones suelen empezar siendo pequeñas y prácticas. Pero una vez que varios sistemas dependen de ellas, se convierten en parte del funcionamiento del negocio. Pequeños puntos poco claros, como qué significa un error concreto o si es seguro enviar una solicitud dos veces, terminan causando problemas en todas partes. La confiabilidad comienza por aclarar esas cosas.
Describir la tarea en palabras sencillas primero
Antes de escribir cualquier código, describo para qué sirve realmente la conexión. ¿Qué le pide un sistema al otro que haga? ¿Qué debe ser cierto antes de que pueda suceder? ¿Cómo sabemos que ha terminado? ¿Cuáles son las respuestas 'no' normales, como 'sin stock', y qué cuenta como un fallo genuino?
Esto mantiene la conexión centrada en la tarea de negocio en lugar de en cómo está dispuesta la base de datos hoy. También asegura que todo el mundo entienda lo mismo por la misma palabra. Si 'completo' significa 'enviado' en un lugar y 'pagado' en otro, alguien acabará cometiendo un error costoso.
Hacer que los mensajes de error sean útiles
Cuando algo es rechazado, el mensaje debe decir qué salió mal y qué hacer al respecto. 'La fecha de entrega no puede ser anterior a hoy' es útil. 'Algo salió mal' no lo es.
Diferentes problemas merecen diferentes respuestas: información faltante, un registro que no existe, dos personas cambiando lo mismo a la vez, falta de permisos o un fallo real del sistema. Los mensajes de error tampoco deben revelar detalles internos como contraseñas o cómo está construida la base de datos. Esos pertenecen a los registros privados, donde puedo rastrear exactamente qué sucedió.
Planificar para la solicitud que se envía dos veces
He aquí un problema común. Un sistema envía un pedido, el otro lado lo guarda, pero la respuesta se pierde por el camino. El remitente no sabe que funcionó, así que lo intenta de nuevo. Ahora hay dos pedidos.
La solución es dar a cada solicitud su propio número de referencia, para que el sistema receptor pueda decir 'ya tengo esta' y simplemente devolver el resultado original. Para cualquier cosa que cree pedidos, pagos o envíos, considero que esto es esencial.
Algunas tareas también tardan un tiempo, como generar un informe extenso o procesar un gran lote de registros. En esos casos, el sistema debería responder de inmediato con un 'recibido, aquí hay una referencia para consultar', en lugar de dejar que el remitente adivine si un largo silencio significa éxito o fracaso.
Cambiar con cuidado
Una vez que otros sistemas dependen de una conexión, cambiarla es un poco como cambiar las reglas de un juego a la mitad. Eliminar una pieza de información es obviamente arriesgado. Cambiar silenciosamente lo que significa una pieza de información puede ser igual de malo y mucho más difícil de detectar.
Cuando se necesitan cambios, añado la nueva versión junto a la antigua siempre que sea posible, aviso a todo el mundo y establezco un cronograma antes de retirar nada, y compruebo quién sigue usando la versión antigua antes de desactivarla.
Cuidar la conexión una vez que esté en funcionamiento
Una conexión que funciona en la computadora de un desarrollador no está terminada. En el uso real también necesita:
- verificar quién pregunta y qué tiene permiso para ver
- limitar cuánto puede enviar cada solicitante, para que un sistema defectuoso no pueda saturarlo
- mantener la información cifrada mientras viaja
- ser monitoreada, para que las ralentizaciones y los errores se detecten pronto
- venir con ejemplos claros, para que las personas que se conecten a ella lo hagan bien a la primera
La prueba de una buena conexión es sencilla: los sistemas que la usan pueden depender de ella, y las personas que la cuidan pueden entender qué está haciendo.
En resumen
Una conexión confiable hace que lo correcto sea fácil de hacer y que los problemas sean fáciles de entender. Los acuerdos claros, el manejo seguro de las repeticiones, los cambios cuidadosos y un buen monitoreo no son extras que se añaden al final. Son parte de una construcción adecuada.