API 专用地址与环境
Sursa API 有自己的专用地址，与用户在浏览器中打开 Sursa 的地址分开。所有路径都以 /v1 开头。
| Sursa 的运行位置 | API 专用地址 | 本门户 |
|---|---|---|
| Sursa 云 | https://api.sursa.com | https://developers.sursa.com |
| 您自己的部署 | https://api.<your domain>，由管理员配置 | API 专用地址上的 /developers/ |
| 没有单独 API 专用地址的部署 | 部署的主地址 | 主地址上的 /developers/ |
API 专用地址只提供 API：没有登录页面，不使用 Cookie，也没有 Web 界面。每个请求都用 API 密钥或 OAuth 访问令牌进行身份验证。该地址背后可能由负载均衡器后的多台服务器提供服务；集成不需要知道有多少台。
在主地址上调用 API 的集成（例如 https://app.sursa.com/v1）仍然有效。少数差异和分步迁移方法参见迁移到 API 专用地址。
基础 URL
所有请求都基于配置中的一个基础 URL 构建，这样同一份代码可以在任何环境中运行：
export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"
只使用 HTTPS，并且不要让密钥出现在您发出的请求的日志中。
版本与规范
GET /v1/health 说明该地址是否可用，并返回为该地址提供服务的 Sursa 的版本。调用它不需要密钥，因此可以用于监控：
curl https://api.sursa.com/v1/health{"ok": true, "version": "v1.4.0"}
这是 Sursa 发行版的版本，而不是 API 的版本。API 的版本是其规范中的 info.version。API 的 OpenAPI 3.1 规范发布在同一个地址上，无需身份验证：
| 路径 | 内容 |
|---|---|
GET /openapi.json | 公共规范，servers 中是该地址。 |
GET /v1/openapi-public.json | 同一份规范。支持 ETag 和 If-None-Match。 |
可以用规范生成客户端，把 API 导入 Postman 等工具，或者在 CI 中检查集成只使用了预期版本中的操作。本门户的 API 参考也是根据同一个文件生成的。
测试
Sursa 没有单独的测试模式：使用密钥的每个请求都作用于其所属组织的真实数据。要安全地开发和测试：
- 为开发单独创建一个密钥，只授予工作所需的最小角色和权限范围。
- 写入一个专用的合集（例如
sandbox），只让您的团队可见，用完后删除。 - 如果公司有单独用于测试的 Sursa 组织或部署，把基础 URL 和密钥指向它即可，代码的其他部分无需更改。
- 从一开始就让重试变得安全：每个
POST和PATCH请求都传入 Idempotency-Key。
API 参考中每个接口页面上的在线调试控制台使用您粘贴的密钥发送真实请求。密钥只保存在浏览器标签页的内存中，只会发送到 API 专用地址。
网络要求
- 允许从您的服务器向 API 专用地址发起出站 HTTPS 连接（端口 443）。
- 网络条件允许时，在防火墙规则中放行主机名，而不是固定的 IP 地址：扩容时，该地址背后的服务器可能会变化。
- 浏览器应用可以直接调用 API：响应允许任何源（
Access-Control-Allow-Origin: *），不使用 Cookie。请注意，在浏览器中使用的密钥对该浏览器的用户可见。