API REST

La interfaz de programación de aplicaciones (API) Representational State Transfer (REST) publica actualizaciones de estado y abre o cierra incidentes. No puede leer datos.

Pestaña de claves de API

Claves de API

  • Una clave pertenece a un servicio y solo puede actuar sobre ese servicio.
  • Los miembros ADMIN crean y revocan claves en la pestaña Claves de API.
  • La clave se muestra una sola vez, justo después de generarla. Solo se guarda un hash.
  • Las claves no caducan. Revoca una clave para que deje de funcionar.

Autenticación

Envía la clave en cualquiera de las dos cabeceras:

Authorization: Bearer <key>
X-Api-Key: <key>

Endpoints

Método y ruta Finalidad Éxito
POST /api/v1/services/{slug}/status Publicar una actualización de estado. 201
POST /api/v1/services/{slug}/incidents Abrir un incidente con su primera actualización. 201
PATCH /api/v1/incidents/{id}/close Cerrar un incidente. 200

Cuerpo de una actualización de estado

{
  "status": "DEGRADED",
  "message": "Markdown text, up to 4096 characters",
  "componentId": "optional UUID",
  "incidentId": "optional UUID of an open incident"
}

status es uno de OK, DEGRADED, CRITICAL, MONITORING, MAINTENANCE, OFFLINE, con cualquier combinación de mayúsculas y minúsculas.

Cuerpo de un incidente

{
  "title": "up to 256 characters",
  "status": "CRITICAL",
  "message": "up to 4096 characters",
  "componentId": "optional UUID"
}

Aquí status debe usar el nombre exacto en mayúsculas.

Errores

Los errores son documentos de problema RFC 7807.

Causa Código de estado
Servicio, incidente o componente desconocido 404
Entrada no válida, estado desconocido, incidente cerrado, clave de otro servicio 400
Acción no permitida 403

Las actualizaciones publicadas mediante la API desencadenan los mismos correos que las publicadas en el panel de gestión.