{ "openapi": "3.1.0", "info": { "title": "Mono · Bre-B — Status Page API", "version": "1.0.0", "description": "API pública para gestionar componentes, incidentes y actualizaciones del status page de Mono · Bre-B. Todos los endpoints bajo `/api/public/*` requieren el header `Authorization: Bearer `, salvo `GET /rss.xml`." }, "servers": [ { "url": "https://status.breb.app" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "STATUS_API_KEY emitida por el equipo de Mono." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } }, "ComponentStatus": { "type": "string", "enum": [ "operational", "degraded", "partial_outage", "major_outage", "maintenance" ] }, "ComponentGroup": { "type": "string", "enum": [ "mol", "dice", "nodo", "participante" ] }, "IncidentStatus": { "type": "string", "enum": [ "investigating", "identified", "monitoring", "resolved" ] }, "Severity": { "type": "string", "enum": [ "minor", "major", "critical" ] }, "Component": { "type": "object", "required": [ "id", "slug", "name", "group", "current_status", "is_primary" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "group": { "$ref": "#/components/schemas/ComponentGroup" }, "is_primary": { "type": "boolean" }, "current_status": { "$ref": "#/components/schemas/ComponentStatus" } } }, "Incident": { "type": "object", "required": [ "id", "title", "status", "severity", "component_id", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/IncidentStatus" }, "severity": { "$ref": "#/components/schemas/Severity" }, "component_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true } } }, "IncidentUpdate": { "type": "object", "required": [ "id", "status", "message", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/IncidentStatus" }, "message": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "MaintenanceStatus": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled" ] }, "Maintenance": { "type": "object", "required": [ "id", "title", "status", "component_id", "scheduled_start", "scheduled_end" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/MaintenanceStatus" }, "component_id": { "type": "string", "format": "uuid" }, "scheduled_start": { "type": "string", "format": "date-time" }, "scheduled_end": { "type": "string", "format": "date-time" } } } }, "responses": { "Unauthorized": { "description": "Falta o es inválida la API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "El body no pasó validación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Recurso no encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/public/incidents": { "post": { "summary": "Crear incidente", "description": "Crea un incidente y su primer update. Si el `component_slug` no existe y se incluye `auto_create_participant`, se crea automáticamente un componente nuevo en el grupo `participante` (caso típico: monitoreo descubre un participante no registrado).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "component_slug", "message" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "component_slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 100 }, "severity": { "$ref": "#/components/schemas/Severity", "default": "minor" }, "status": { "$ref": "#/components/schemas/IncidentStatus", "default": "investigating" }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "auto_create_participant": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 280 } } } } } } } }, "responses": { "201": { "description": "Incidente y update creados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "incident": { "$ref": "#/components/schemas/Incident" }, "update": { "$ref": "#/components/schemas/IncidentUpdate" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/public/incidents/{id}/updates": { "post": { "summary": "Agregar update a un incidente", "description": "Añade una actualización al incidente. Si `status='resolved'`, se marca `resolved_at` y se cierra el incidente.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "$ref": "#/components/schemas/IncidentStatus" }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "Update creado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "update": { "$ref": "#/components/schemas/IncidentUpdate" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/public/incidents/{id}/resolve": { "post": { "summary": "Resolver incidente", "description": "Atajo para cerrar un incidente. El body es opcional.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Incidente cerrado." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/public/components": { "get": { "summary": "Listar componentes", "description": "Devuelve todos los componentes registrados (MOL, DICE, nodos y participantes). Útil para descubrir el `slug` real antes de crear incidentes o mantenimientos. No requiere API key.", "parameters": [ { "name": "group", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mol", "dice", "nodo", "participante" ] }, "description": "Filtra por grupo." } ], "responses": { "200": { "description": "Lista de componentes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/Component" } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "summary": "Crear participante", "description": "Crea manualmente un componente en el grupo `participante`. Útil cuando se necesita registrar un participante antes de tener un incidente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 280 } } } } } }, "responses": { "201": { "description": "Componente creado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "component": { "$ref": "#/components/schemas/Component" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "El slug ya existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/components/{slug}": { "patch": { "summary": "Actualizar estado de un componente", "description": "Cambia manualmente el `current_status` (útil para ventanas de mantenimiento).", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "current_status" ], "properties": { "current_status": { "$ref": "#/components/schemas/ComponentStatus" } } } } } }, "responses": { "200": { "description": "Componente actualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "component": { "$ref": "#/components/schemas/Component" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/public/maintenances": { "get": { "summary": "Listar mantenimientos activos", "description": "Devuelve mantenimientos con estado `scheduled` o `in_progress`. No requiere autenticación.", "security": [], "responses": { "200": { "description": "Listado de mantenimientos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "maintenances": { "type": "array", "items": { "$ref": "#/components/schemas/Maintenance" } } } } } } } } }, "post": { "summary": "Crear mantenimiento programado", "description": "Crea un mantenimiento programado para un componente. Soporta `auto_create_participant` igual que `/incidents`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "component_slug", "scheduled_start", "scheduled_end" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "component_slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 100 }, "scheduled_start": { "type": "string", "format": "date-time" }, "scheduled_end": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/MaintenanceStatus", "default": "scheduled" }, "auto_create_participant": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 280 } } } } } } } }, "responses": { "201": { "description": "Mantenimiento creado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "maintenance": { "$ref": "#/components/schemas/Maintenance" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/public/maintenances/{id}": { "patch": { "summary": "Actualizar mantenimiento", "description": "Modifica título, ventana o estado de un mantenimiento.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000, "nullable": true }, "scheduled_start": { "type": "string", "format": "date-time" }, "scheduled_end": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/MaintenanceStatus" } } } } } }, "responses": { "200": { "description": "Mantenimiento actualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "maintenance": { "$ref": "#/components/schemas/Maintenance" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Cancelar mantenimiento", "description": "Marca el mantenimiento como `cancelled`. No elimina el registro.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Mantenimiento cancelado." }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/rss.xml": { "get": { "summary": "Feed Atom de incidentes", "description": "Feed público con los últimos 50 incidentes y sus updates. No requiere autenticación.", "security": [], "responses": { "200": { "description": "Feed Atom.", "content": { "application/atom+xml": { "schema": { "type": "string" } } } } } } } } }