Wakapi项目API接口使用指南
项目概述
Wakapi是一个开源的编程时间追踪工具，它可以帮助开发者记录和分析自己的编码活动。通过收集开发者在各种项目中的工作时间数据，Wakapi能够提供有价值的统计信息，帮助开发者了解自己的工作习惯和效率。
API基础配置
在使用Wakapi API之前，需要进行一些基础配置：
-
基础URL设置：所有API请求都需要基于一个基础URL，通常设置为
http://localhost:3000（本地开发环境）或您的Wakapi服务器地址。 -
认证方式：Wakapi API使用Basic Auth认证，需要将API密钥进行Base64编码后放在请求头的
Authorization字段中。
主要API接口介绍
1. 健康检查接口
端点：GET /api/health
这是一个简单的健康检查接口，用于验证Wakapi服务是否正常运行。不需要任何认证信息，返回200状态码表示服务健康。
2. 指标接口
端点：GET /api/metrics
此接口返回Wakapi服务的各种内部指标数据，需要认证。返回的数据可能包括服务运行时间、活动记录数等系统指标。
3. 活动记录接口
端点：POST /api/heartbeat
这是Wakapi最核心的接口之一，用于上报开发者的编码活动。每个活动记录包含以下信息：
entity：正在编辑的文件路径project：所属项目名称language：编程语言is_write：是否为写入操作type：实体类型（通常为"file"）time：时间戳
示例请求体：
[{
"entity": "/home/user1/dev/proejct1/main.go",
"project": "Project 1",
"language": "Go",
"is_write": true,
"type": "file",
"time": 1616680499.113417
}]
4. 摘要统计接口
端点：GET /api/summary
此接口返回用户的编码活动摘要统计信息。可以通过interval参数指定统计时间范围，如last_7_days表示最近7天。
5. Shields兼容接口
端点：GET /api/compat/shields/v1/{username}/interval:{interval}/language:{language}
此接口提供与Shields.io兼容的数据格式，可用于生成各种徽章。参数说明：
username：Wakapi用户名interval：时间范围（如today）language：编程语言（如Go）
6. WakaTime兼容接口
Wakapi提供了一系列与WakaTime API兼容的接口，方便从WakaTime迁移的用户：
-
总时间统计：
GET /api/compat/wakatime/v1/users/current/all_time_since_today -
活动记录获取：
GET /api/compat/wakatime/v1/users/current/heartbeats?date=YYYY-MM-DD -
统计数据：
GET /api/compat/wakatime/v1/users/current/stats或带时间范围的：GET /api/compat/wakatime/v1/users/current/stats/last_7_days -
摘要数据：
GET /api/compat/wakatime/v1/users/current/summaries?start=...&end=... -
状态栏数据：
GET /api/compat/wakatime/v1/users/current/statusbar/today
错误诊断接口
端点：POST /api/plugins/errors
此接口用于接收客户端诊断信息，帮助开发者排查问题。请求需要包含详细的错误日志和堆栈跟踪信息。
使用建议
-
认证处理：所有需要认证的接口都需要在请求头中添加
Authorization: Basic {base64_encoded_api_key}。 -
机器标识：上报活动时建议添加
X-Machine-Name头，标识数据来源的机器。 -
用户代理：建议设置合理的
User-Agent头，便于服务端统计客户端类型。 -
错误处理：客户端应妥善处理API返回的各种HTTP状态码，特别是401（未授权）和429（请求过多）。
-
数据上报频率：活动上报不宜过于频繁，通常建议5-15分钟上报一次活动状态。
通过合理使用这些API接口，开发者可以构建自己的编码时间追踪系统，或与现有工具集成，实现个性化的开发效率分析。
