Plantilla de Página de Estado de API
Una plantilla para una página de estado de API pública que comunica uptime, incidentes y ventanas de mantenimiento a los consumidores.
Nota para desarrolladores hispanohablantes: Esta guía incluye ejemplos y convenciones de nomenclatura adaptadas a equipos que trabajan en español. Cuando existen diferencias significativas en terminología técnica entre el inglés y el español, se indican explícitamente para facilitar la comunicación en equipos multiculturales.
Mejores Prácticas
- Actualiza cada 15-30 minutos durante incidentes activos — El silencio hace que los consumidores asuman lo peor
- Publica mantenimientos programados con 7 días de anticipación — Da tiempo a los consumidores para preparar alternativas
- Usa un dominio separado —
status.example.comno debe depender de la API que monitorea - Ofrece suscripciones RSS / email / Slack — Permite que los consumidores elijan cómo recibir actualizaciones
- Muestra uptime histórico — Un gráfico de 30 o 90 días genera confianza
- Sé honesto sobre rendimiento degradado — No marques un servicio como “operacional” cuando la latencia es 10x la normal
- Enlaza a postmortems de incidentes — La transparencia después de la resolución genera confianza a largo plazo
Errores Comunes
- Usar la misma infraestructura que la API para la página de estado — si la API cae, la página de estado también
- Marcar incidentes como resueltos demasiado pronto — espera hasta que las métricas confirmen recuperación por al menos 10 minutos
- Borrar o editar el historial de incidentes resueltos — los consumidores necesitan referenciar incidentes pasados
- Actualizaciones vagas como “estamos investigando” — comparte lo que sabes y lo que no sabes
- No definir niveles de severidad — los consumidores no pueden evaluar el impacto sin definiciones claras
Preguntas Frecuentes
¿La página de estado debería ser pública o solo interna?
Pública para APIs orientadas a clientes. Solo interna para servicios puramente internos. Las páginas de estado públicas reducen tickets de soporte y demuestran madurez operacional.
¿Con qué frecuencia debo actualizar durante un incidente?
Cada 15-30 minutos, incluso si no hay información nueva. Un mensaje como “Seguimos investigando la causa raíz, próxima actualización a las 15:00 UTC” es mejor que silencio.
¿Qué debo hacer si un incidente excede el SLA?
Comunícate proactivamente. No esperes a que los clientes se quejen. Emite un resumen explicando qué pasó, por qué excedió el SLA y qué medidas se están tomando para prevenir recurrencias. Algunas empresas ofrecen créditos de servicio por incumplimientos de SLA.