Kener项目API接口详解与使用指南

项目概述

Kener是一个自托管的Node.js状态页面和事件管理系统，提供了完整的API接口规范，用于监控系统状态和管理事件。通过这套API，开发者可以实时监控系统状态、记录事件并管理事件生命周期。

API基础信息

Kener API遵循OpenAPI 3.0规范，当前版本为3.0.0。所有API请求都需要通过JWT令牌进行身份验证，采用Bearer Token方式。

认证方式

{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT"
  }
}

核心API功能详解

1. 监控状态管理

1.1 更新监控状态

端点: POST /api/status

功能: 更新指定监控标签的状态信息

请求体示例:

{
  "status": "UP",
  "latency": 100,
  "timestampInSeconds": 1731251760,
  "tag": "earth"
}

状态值说明:

• UP: 服务正常
• DOWN: 服务中断
• DEGRADED: 服务降级

响应示例:

{
  "status": 200,
  "message": "success at 1731251760"
}

1.2 获取监控状态

端点: GET /api/status?tag={tag}

参数:

• tag: 监控标签名称(必填)

响应示例:

{
  "status": "UP",
  "uptime": "100",
  "last_updated_at": 1731251760
}

2. 事件管理

2.1 创建事件

端点: POST /api/incident

请求体示例:

{
  "start_date_time": 1731901920,
  "title": "Outage in mumbai"
}

响应示例:

{
  "id": 4,
  "start_date_time": 1731901920,
  "title": "Outage in mumbai",
  "status": "OPEN",
  "state": "INVESTIGATING",
  "created_at": "2025-01-09 04:12:01"
}

2.2 查询事件

端点: GET /api/incident

查询参数:

• status: 事件状态(OPEN/CLOSED)
• state: 事件处理状态(INVESTIGATING/IDENTIFIED/MONITORING/RESOLVED)
• page: 页码
• limit: 每页数量
• start_date_time: 开始时间戳
• end_date_time: 结束时间戳

响应示例:

[
  {
    "id": 2,
    "title": "future wala",
    "start_date_time": 1736774486,
    "status": "OPEN",
    "state": "RESOLVED"
  }
]

3. 事件评论管理

3.1 添加评论

端点: POST /api/incident/{incident_id}/comment

请求体示例:

{
  "comment": "This is a comment",
  "commented_at": 1736398336,
  "state": "IDENTIFIED"
}

响应示例:

{
  "id": 60,
  "comment": "Sometimes, you want all the goodness of moment",
  "incident_id": 24,
  "status": "ACTIVE",
  "state": "MONITORING"
}

数据结构详解

1. 监控状态对象(MonitorStatus)

{
  "status": "string(UP/DOWN/DEGRADED)",
  "latency": "number(秒)",
  "timestampInSeconds": "integer(UTC时间戳)",
  "tag": "string(监控标签)"
}

2. 事件对象(Incident)

{
  "id": "integer",
  "title": "string",
  "start_date_time": "integer(UTC时间戳)",
  "end_date_time": "integer(UTC时间戳)",
  "status": "string(OPEN/CLOSED)",
  "state": "string(INVESTIGATING/IDENTIFIED/MONITORING/RESOLVED)"
}

3. 评论对象(Comment)

{
  "id": "integer",
  "comment": "string",
  "incident_id": "integer",
  "commented_at": "integer(UTC时间戳)",
  "state": "string(事件状态)"
}

最佳实践建议

1. 监控状态更新:

   • 建议设置定时任务，定期(如每分钟)上报监控状态
   • 对于关键服务，可以设置更频繁的上报间隔
   • 确保时间戳使用UTC时间，避免时区问题

2. 事件管理:

   • 创建事件时应提供详细的标题和准确的开始时间
   • 事件状态(state)应按实际处理进度及时更新
   • 通过评论记录事件处理过程中的关键信息

3. 错误处理:

   • 所有API调用都应处理401未授权错误
   • 对于400错误，检查请求参数是否符合规范
   • 建议实现自动重试机制处理临时性错误

常见问题解答

Q: 如何获取有效的API密钥？ A: API密钥需要在Kener系统管理界面生成，每个密钥应有明确的用途描述和访问权限控制。

Q: 监控状态中的latency单位是什么？ A: latency单位为秒，表示服务的响应延迟时间。

Q: 事件状态(status)和处理状态(state)有什么区别？ A: status表示事件是否已关闭(OPEN/CLOSED)，state表示事件当前的处理阶段(调查中/已识别/监控中/已解决)。

Q: 时间戳应该使用什么格式？ A: 所有时间戳都应使用UTC时间的秒级时间戳，避免时区转换问题。

通过本文的详细讲解，开发者可以全面了解Kener项目的API接口规范和使用方法，从而更好地集成和使用这套状态监控和事件管理系统。