La API REST

Todas las rutas de esta página cuelgan de la URL base de abajo, y cada petición lleva su clave en una cabecera Authorization. No hay otra manera de entrar: ni cookie de sesión, ni autenticación básica, ni clave en la cadena de consulta.

curl -s https://app.provibr.com/api/v1/me \
  -H "Authorization: Bearer pvk_..."

Una clave se crea en la propia página de perfil, en «Claves de API». Pertenece a una sola persona y a una sola cuenta: no se comparte con los compañeros y deja de funcionar en el momento en que esa persona abandona la cuenta.

• Una clave caduca al cabo de 90 días salvo que se elija otra cosa. Se puede escoger un plazo más corto, o ninguno; una clave sin fecha de fin es una clave que hay que acordarse de revocar a mano.
• Rotar consiste en crear una clave nueva y revocar la anterior, con un momento intermedio en el que las dos funcionan. No se puede rotar el secreto de una clave sin cambiar de clave, porque eso dejaría sin ninguna clave utilizable si algo saliera mal a mitad de camino.
• Una clave se puede atar a una lista de direcciones. Una petición que llegue desde cualquier otro sitio se rechaza antes de leer nada, y ese rechazo no le dice nada sobre la clave a quien llama.
• Un miembro tiene como máximo 25 claves. Una clave revocada conserva su fila, así que después se puede seguir viendo qué se le permitía hacer mientras estuvo activa.

Una clave lleva permisos: de lectura o de escritura, por cada parte del panel. Lo que puede hacer realmente es la intersección de esos permisos y los del miembro al que pertenece.

Los permisos se leen en vivo, en cada petición. Si se le retira algo a un miembro, todas sus claves quedan más restringidas al instante, sin que nadie tenga que revocar nada. Por eso mismo una clave sobrevive a un cambio de rol en lugar de quedar invalidada por él.

Su infraestructura solo es accesible a través del agente que está dentro de su propia red, y ese agente conecta hacia fuera. Por eso un endpoint que modifica una máquina no puede responder con el resultado: responde que la orden se ha aceptado y entrega algo con lo que hacer el seguimiento.

1. 01Se envía la petición y llega una respuesta de aceptación, con una cabecera Location que apunta al comando que se ha creado. Esa cabecera es absoluta desde el host: hay que resolverla contra el origen y no contra la URL base de arriba, o se acaba pidiendo una ruta que no existe.
2. 02Ese mismo comando viene también en el cuerpo, pero envuelto en un campo command. La lectura de abajo lo devuelve desnudo, sin esa envoltura: basta con desenvolverlo una vez y la primera lectura suele ser innecesaria.
3. 03Se lee el comando hasta que su estado es definitivo: completado, fallido, caducado o cancelado. Solo pendiente no es definitivo, y un estado desconocido cuenta también como definitivo, de modo que un valor añadido más adelante nunca deja el bucle abierto para siempre.
4. 04Un comando fallido lleva el código de error del propio agente, con sus parámetros: los mismos que el panel muestra en pantalla.

# 1. the order - answers 202 with a Location header
curl -s -D - -X POST https://app.provibr.com/api/v1/servers/<serverId>/actions/start \
  -H "Authorization: Bearer pvk_..."

# 2. the outcome - repeat until the status is final
curl -s https://app.provibr.com/api/v1/commands/<commandId> \
  -H "Authorization: Bearer pvk_..."

Cada endpoint dice con qué responde: 200 en una lectura, 201 cuando se ha creado algo, 202 cuando el agente todavía tiene trabajo por hacer. Y todos describen el cuerpo que devuelven, con un nombre propio por recurso, de modo que el código generado tiene un tipo por recurso y no uno por endpoint.

Las listas responden con una página y un cursor; ese cursor se devuelve una y otra vez hasta que sale vacío. Una página contiene 50 filas por defecto y 100 como máximo.

Toda respuesta que no sea un éxito tiene la misma forma, con independencia de qué haya fallado y de dónde haya fallado.

{
  "error": {
    "code": "validation_failed",
    "message": "Name is too long (max 64).",
    "detail": "server.validation.apiKeys.nameTooLong",
    "params": { "max": 64 },
    "requestId": "3f9c1b2a-..."
  }
}

code

La palabra sobre la que ramificar. Sale de una lista cerrada, así que un valor desconocido significa que se está hablando con una versión más nueva que aquella sobre la que se construyó.

message

Una frase en inglés, para quien lea un registro. Nunca hay que ramificar sobre ella: la redacción puede cambiar.

detail

Un identificador estable, cuando lo hay. Es el mismo que el panel utiliza para componer su propio mensaje, así que la frase se puede redactar en el idioma que corresponda.

params

Los parámetros que acompañan a ese identificador: un límite que se ha superado, un nombre que ya estaba ocupado, el host que ha rechazado la conexión.

requestId

El identificador de esta petición, presente también en una cabecera de la respuesta. Conviene citarlo al consultarnos algo.

Se pueden hacer 120 peticiones por minuto y por clave, y 600 por cuenta sumando todas sus claves. Ese segundo límite existe para que veinte claves no puedan cargar veinte veces el mismo host.

Todo lo que crea algo acepta una cabecera idempotency-key elegida por quien llama. Si se repite la misma petición con el mismo valor, se recupera el primer resultado en lugar de obtener una segunda máquina, una segunda clave o un segundo comando.

También se puede enviar un x-request-id propio. Vuelve en la respuesta y aparece en nuestros registros, que es la forma más barata de poner una línea del registro propio junto a una línea del nuestro.

En el enrutado de esta API no hay ni un solo nombre de proveedor. Qué sistemas se pueden conectar, qué campos llevan sus credenciales y de qué son capaces lo responde el endpoint de descubrimiento, y el cuerpo que se envía para crear una integración se construye a partir de ese mismo registro. Un proveedor que entra en servicio aparece en los dos sin que cambie ni un solo endpoint.

También funciona al revés. Pedirle a una máquina algo que su proveedor no sabe hacer (una consola en una cuenta de hosting, un disco en un servidor de juego) devuelve un rechazo que nombra la capacidad que falta, antes de que se envíe nada al agente.

Agrupados igual que los agrupa la especificación. Cada ruta va detrás de la URL base y a su lado figura el permiso que exige el endpoint; donde no figura nada, basta con una clave válida.

La misma información en forma de documento OpenAPI 3.1, generado a partir del código que sirve estos endpoints en vez de escrito al lado. Se le puede entregar a un generador de clientes, a un editor o a un conjunto de pruebas.

curl -s https://app.provibr.com/api/v1/openapi.json

Dentro de esta versión, los cambios son añadidos: endpoints nuevos, campos opcionales nuevos, valores nuevos en una lista. Conviene leer con tolerancia los campos desconocidos y no tratar como fatal un código de error que no se conozca.