SuperAPI AI 工具集

api-integration

编程与开发

查看项目

更新于 10-15 17:22

技能介绍

用途:在集成外部 REST API、构建 API 客户端或封装层、处理 API 认证、实现限流与缓存时启用本技能。

主要能力与原则:尊重限流,把 API 视为共享资源;认证密钥存放在 secrets.json,绝不写进代码;优雅处理错误,实现重试与退避;适当时缓存响应以减少重复请求。

认证方式:密钥写入 secrets.json(含 github_token、openweather_api_key 等键),通过 Python 的 load_secrets() 读取,找不到时可回退环境变量,无密钥则抛出 ValueError。Bash 中可用 python3 从 secrets.json 读取密钥后配合 curl 请求。

请求与容错:基础 GET 使用 requests,设置 Authorization 头与超时并调用 raise_for_status();重试版本对 429 等待并指数退避,其他状态码打印错误返回 None。错误处理区分 HTTPError(429 被限流、401 未授权)、ConnectionError 与 Timeout。状态码对照:200 成功、401 检查密钥、403 检查权限、404 核对端点、429 等待重试、5xx 退避重试。

缓存与限流:用内存缓存加 TTL(如 3600 秒)复用结果;通过响应头 x-ratelimit-limit / x-ratelimit-remaining 检查配额;批量请求用 time.sleep 加延迟;分页通过 page 与 per_page 循环抓取并每次 sleep 1 秒。

Grove 应用约定(强制性):API 路由错误响应必须使用 Signpost 错误码,不得返回临时 JSON 形状;服务端引入 API_ERRORS、buildErrorJson、logGroveError,返回如 401 时用 json(buildErrorJson(API_ERRORS.UNAUTHORIZED), { status: 401 }),无效请求体用 API_ERRORS.INVALID_REQUEST_BODY。客户端使用 apiRequest()(处理 CSRF 与凭证)并用 toast 提示成功或失败。完整参考见 AgentUsage/error_handling.md。

最佳实践:密钥存 secrets.json;实现指数退避重试;适当缓存;尊重限流;优雅处理错误;记录请求时避免敏感数据。避免硬编码密钥、忽视限流、跳过错误处理、紧密循环请求、记录 API 密钥。

限制与说明:资料未提供具体收费、价格、平台支持范围或性能数据,也未给出各外部 API 的独立配额细节;实际可用性取决于目标 API 的文档与条款。