Referencia de la API REST

De dónde sale esta página

Esta referencia no se escribe, se lee. Cada ruta, cada método y cada ámbito de aquí abajo vienen del contrato OpenAPI compilado dentro del binario de la API, y una comprobación coteja ese contrato con el código en ejecución en cada compilación.

Una referencia mantenida a mano empieza a divergir la semana siguiente a escribirla, y desde ese momento es peor que ninguna referencia, porque se la cree. La única forma de no divergir es no tener una segunda copia de la que divergir.

Aquí se enumeran las operaciones que una clave API puede llamar, y ninguna más. El resto del servicio lo gobierna el panel con rutas que solo alcanza una sesión del navegador: no forman parte de la API pública, cambian sin aviso, y documentarlas las convertiría en una promesa que nadie ha hecho.

Aquí encuentras la superficie: dónde vive una ruta y para qué sirve. El resto lo lleva el contrato — esquemas de petición y respuesta, códigos de error, límites de frecuencia — y es el documento que hay que leer cuando una llamada responde algo que no esperabas. La copia que puedes descargar contiene las mismas operaciones que esta página, y solo esas.

Autenticación

Tres formas de demostrar quién eres, y no son intercambiables. La clave con ámbitos es la pensada para los programas; la sesión es la que guarda tu navegador mientras usas el panel.

Los ámbitos de escritura no incluyen los de lectura. Si no, quien mira una clave vería jobs:write y tendría que acordarse de que también cubre la lectura.

Las operaciones que no aceptan ninguna clave — emitir credenciales, comprometer un pago, destruir una cuenta — faltan de esta página justo por eso. Es una decisión y no un olvido: una clave capaz de crear otra dejaría sin sentido revocar la primera.

Operaciones

Agrupadas como las agrupa el contrato. Un tramo de ruta entre llaves es un parámetro que sustituyes; la columna del ámbito dice qué debe llevar una clave para que esa llamada pase.