PathSeptiembre de 2026
Pathly como API, y un provider de Terraform
Describir la infraestructura en ficheros y crear la vigilancia a mano es mantener dos verdades que acaban divergiendo. Ahora se escribe como código: una API documentada y un provider de Terraform.
El contrato publicado es el que corre
La API sirve su propio contrato OpenAPI, sin autenticación, en una dirección pública. Ese documento no se escribe aparte del código: se genera a partir de la tabla que declara las rutas, la misma que decide, en cada llamada, qué alcance se exige. Una ruta que no figura en ella no arranca. La página de desarrolladores lee ese contrato en el momento del renderizado, de modo que una ruta retirada desaparece de la documentación sin que nadie lo piense. Una documentación copiada a mano siempre miente, la única pregunta es desde cuándo.
Alcances estrechos, y cuatro negativas
Una clave lleva alcances con la forma recurso y luego acción: leer los escenarios, escribirlos, lanzar una ejecución, cerrar un incidente. Escribir implica leer, porque una herramienta siempre relee lo que acaba de escribir. Lanzar sigue separado de leer, porque una ejecución consume cuota y no es una consulta.
Cuatro gestos quedan fuera del alcance de una clave, por decisión y no por olvido. Emitir o revocar una clave, porque una clave capaz de eso anula los alcances de todas las demás. Invitar a un miembro, porque es lo mismo por un rodeo: la nueva cuenta emitirá las claves que quiera. Cambiar de plan o tocar la facturación, porque un token de integración continua no debe comprometer gastos. Exportar la organización, porque la exportación contiene miembros, es decir, datos personales.
Lo que nunca se relee
Una contraseña de autenticación, la dirección de un webhook, los pasos de un recorrido de navegador: esos valores se escriben y no vuelven a salir. En su lugar, la API devuelve una huella de doce caracteres, que cambia en cuanto cambia el valor. Es suficiente para que una herramienta detecte que un recurso se modificó en otro sitio, y demasiado poco para reconstruir lo que contiene. Terraform lo usa exactamente así: el destino de un webhook editado a mano en la consola se ve en el siguiente plan, sin que la dirección se escriba nunca en un fichero de estado.
Lo que una herramienta automática espera de una API
- Una paginación por cursor, no por número de página: un recurso creado durante el recorrido desplazaría las páginas, y el cliente releería una fila o se saltaría otra.
- Una cabecera Retry-After cuando se supera el caudal: sin ella, un cliente automatizado reintenta a ciegas y se queda en su propio bucle.
- Una clave de idempotencia repetida durante veinticuatro horas: un pipeline relanzado tras un corte de red no crea duplicados.
- Un identificador que pertenece a otra organización responde 404, nunca 403: responder «prohibido» confirmaría que existe.
El provider
Cuatro recursos —un escenario, una ventana de mantenimiento, un webhook, un objetivo de disponibilidad— y una fuente de datos que relee el inventario, suficiente para detectar un escenario creado a mano en la consola y ausente del código. Las claves de API y los miembros no figuran, por la razón ya dicha: un fichero Terraform que invita a un propietario es una escalada por rodeo.
Dos comportamientos importan más que la lista de recursos. Tras un apply, un plan debe estar vacío: si no, la herramienta propone un cambio en cada pasada y nadie vuelve a leer sus planes. Y cambiar la dirección, el intervalo o el umbral de latencia de un escenario debe modificarlo en su sitio, nunca destruirlo y recrearlo — un escenario recreado pierde su historial y sus incidentes, es decir, todo aquello por lo que se vigilaba. Esos dos puntos exigieron, del lado de la API, que todo lo que se escribe se relea idéntico. Es el trabajo menos visible del provider, y el que decide si es utilizable.
Adoptar un parque existente
Nadie rehace su vigilancia desde cero para pasar al código. Cada recurso se importa por su identificador: el escenario creado el año pasado en la consola entra en el estado de Terraform sin ser tocado, y el siguiente plan muestra la diferencia entre lo que es y lo que describe el fichero. Es la única manera honesta de migrar, y también la que permite dar marcha atrás.
En qué punto está
El provider está publicado en el registro público de Terraform, con su documentación y sus ejemplos: basta con declarar una versión en un bloque required_providers para instalarlo, sin espejo local ni compilación desde las fuentes. La numeración sigue en 0.x, y eso significa algo preciso: los recursos existentes no se moverán sin motivo, pero nos reservamos ajustar un esquema antes del 1.0. La API no espera al provider: una clave, una dirección y la documentación para desarrolladores bastan para pilotar lo mismo desde cualquier lenguaje.