API e integraciones

Qué abarca esta categoría

Aquí caben cuatro trabajos relacionados. Crear y probar peticiones a mano. Documentar una interfaz para que otras personas puedan usarla. Poner una pasarela delante de varios servicios para que las claves, los límites de uso, las cuotas y las versiones se comporten igual en todas partes. Mover datos entre productos que nunca se diseñaron para hablar entre sí.

Los tres primeros son para los equipos que publican una API. El cuarto es para quien une herramientas que ha comprado. Ambos públicos acaban en este estante, y por eso los productos se parecen tan poco entre sí.

La automatización puramente visual, sin código, pertenece a no-code y automatización. Las alertas sobre un servicio en producción están en monitorización.

Clientes y qué los distingue hoy

Todos los clientes envían una petición y muestran una respuesta. Las diferencias están más adentro.

Primero, la gestión de entornos: local, preproducción, producción y lo que un compañero ejecute en su portátil, con cambios limpios sin que nadie edite una URL a mano. Después, los scripts, para que un token se obtenga antes de una petición en lugar de pegarlo cada mañana. Después, las aserciones de prueba, para que una colección se convierta en algo que un servidor de compilación pueda ejecutar.

La colaboración es donde se dividen las opiniones. La sincronización en la nube es cómoda y deja su historial de peticiones en servidores ajenos. Las herramientas basadas en archivos guardan las colecciones en el repositorio, junto al código, de modo que un cambio se revisa como cualquier otro y ningún espacio de trabajo se va con un empleado que se marcha.

Pregunte en cualquier caso dónde viven los secretos. Una clave escrita en una colección exportada es la vía estándar hacia un repositorio público.

Documentación que no se pudre

La documentación escrita a mano queda desactualizada en un trimestre. El único arreglo que sobrevive es generarla a partir de una especificación que vive junto al código y se reconstruye cuando el código se fusiona.

Compruebe tres cosas: si el producto lee el formato de su especificación sin un paso de conversión, si los ejemplos se pueden ejecutar desde la página y si las versiones antiguas siguen publicadas para quienes todavía las usan.

Un registro de cambios importa más que el diseño. Los consumidores necesitan saber qué se rompió y cuándo, y ningún estilo sustituye eso.

Pasarelas y cuándo merecen la pena

Un solo servicio rara vez necesita una pasarela. El caso aparece cuando la autenticación, los límites de uso, las cuotas y las versiones tienen que comportarse de forma idéntica en varios servicios.

En ese punto las preguntas son: dónde se ejecuta y cuánta latencia añade, cómo se definen los límites y qué ve quien llama cuando se alcanza uno, si las claves se pueden rotar sin tiempo de inactividad y qué contienen los registros. Todo lo que termina tráfico se convierte en un riesgo de disponibilidad por sí mismo, así que pregunte qué ocurre cuando la propia pasarela tiene un mal día.

Qué miden los precios

• Puestos en los clientes y los productos de documentación, a veces gratuitos para los revisores de solo lectura.
• Tareas o ejecuciones en las plataformas de integración, contadas por paso y no por flujo.
• Llamadas o ancho de banda en las pasarelas, con una tarifa distinta para lo que se sirve desde caché.
• Retención del historial de ejecuciones, corta en los planes de entrada y corta justo cuando más se necesita.
• Conectores, con los premium aparcados un nivel por encima del plan que se presupuesta.

El precio por tarea merece hacer cuentas antes de firmar. Un flujo de seis pasos que se ejecuta cada diez minutos no es una tarea al mes, y la cifra en que se convierte ha sorprendido a muchos equipos. La misma forma de sorpresa en otras categorías está reunida en lo que ocultan las páginas de precios.

Qué probar

Reconstruya de punta a punta una integración real que ya tenga en marcha, incluida la parte en que la otra parte devuelve un error.

Observe cómo gestiona la herramienta los reintentos, la entrega duplicada, un tercero que se queda colgado y una carga que llega con un campo ausente. Los productos bien hechos permiten repetir una ejecución fallida tras corregir la causa. Los más flojos la pierden en silencio y no dicen nada hasta que lo hace un cliente.

Después compruebe la salida. Las colecciones, las especificaciones y las definiciones de flujos deberían poder exportarse como archivos legibles. Todo lo que queda encerrado en un espacio de trabajo es trabajo que se hará dos veces.

Documentación, versiones y cómo conservar a los consumidores

Una interfaz con usuarios es una promesa, y la mayor parte de la dificultad de esta categoría viene de cambiarla sin romper esa promesa.

Decida un enfoque de versiones antes de que llegue el primer consumidor externo, ya que incorporarlo después supone pedir a todo el mundo que cambie a la vez. Sea cual sea el esquema, publique qué cambió y cuándo, y conceda un periodo de obsolescencia medido en meses y no en semanas.

Los errores merecen tanta atención como los aciertos. Una respuesta que dice qué salió mal, qué campo lo causó y qué hacer a continuación elimina más solicitudes de soporte que cualquier cantidad de prosa.

Luego lea su propia documentación como lo haría un recién llegado. La mejora más rápida que suele haber es un ejemplo funcional al principio de la página en lugar de una tabla de referencia.