API 版本控制
AstroAPI 用兼容性日期而非 URL 中的版本号来管理破坏性变更。端点路径永不改变;你固定一个日期, 就会一直收到该日期当时的行为。
你的版本
在 X-Api-Version 请求头中发送你所依据的兼容性日期:
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01由某个兼容性日期塑形的响应会告诉你是哪一个:
X-Api-Version: 2026-01-01
Vary: X-Api-Version输出不依赖版本的端点会同时省略这两个响应头。GET /api/modules 在任何日期都返回相同的响应体,因此 没有什么可报告的,缓存也无需区分。若你显式发送 X-Api-Version,任何端点都会把它回显给你,于是你 总能确认某个值已被接受。
要读回你的组织解析到哪个版本,使用 GET /api/org/api-version;其中的 effectiveApiVersion 就是 请求未自带请求头时所适用的日期。
若不发送请求头,请求会使用你组织已固定的版本;若你未固定任何版本,则使用基线 2026-01-01。 新行为永远不会自动应用到你身上——今天写好的集成会一直按原样工作,无论我们之后发布什么。
变更日志
每一项破坏性变更都在此列出,并附上生效日期。固定一个日期会给你该日期及之前的全部变更。
| 日期 | 变更 |
|---|---|
2026-09-03 | POST /api/calc/transit 上的 aspects 已分组:每个行运行星、相位与本命行星的组合一条记录,解读文本只出现一次,该时段内的每次经过放在 occurrences 下。此前是每次经过一条记录,且各自重复相同文本。参见行运。 |
2026-09-10 | POST /api/calc/natal 上的每个天体点都带有 declination(度,北为正)和 outOfBounds(超出该日期太阳的最大赤纬)。此前这两个字段都不存在。参见赤纬。 |
基线 2026-01-01 是我们提供的最早版本。固定更早的日期会被接受,并解析为基线。
固定你的组织
与其给每次调用都加一个请求头,不如把组织固定一次。此后所有未指定版本的请求都会使用该日期。
curl -X PATCH "https://api.astroapi.cloud/api/org/api-version" \
-H "Content-Type: application/json" \
-H "X-Api-Key: your_api_key" \
-d '{
"data": {
"type": "organizations",
"attributes": { "apiVersion": "2026-01-01" }
}
}'读回当前固定值,以及你可以选择的范围:
curl "https://api.astroapi.cloud/api/org/api-version" \
-H "X-Api-Key: your_api_key"{
"data": {
"type": "organizations",
"id": "org_123",
"attributes": {
"apiVersion": "2026-01-01",
"effectiveApiVersion": "2026-01-01",
"baselineApiVersion": "2026-01-01",
"latestApiVersion": "2026-01-01"
}
}
}发送 "apiVersion": null 可清除固定值并回落到基线。
安全升级
请求头总是胜过组织固定值,这使得安全上线成为可能:
- 阅读上面的变更日志,检查哪些变更落在你当前日期与新日期之间。
- 在少量请求上,或在你的预发布环境中,用
X-Api-Version发送新日期并验证响应。 - 满意之后,把组织固定到新日期,并再次去掉请求头。
由于请求头会按请求覆盖固定值,你也可以反过来:把组织向前固定,同时从尚未迁移的服务里临时发送较旧 的日期。
浏览器与嵌入式客户端
无法设置请求头的场景——<img>、<iframe> 和 <script> 嵌入、带签名的星盘 URL——改为接受把日期 作为查询参数:
https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...两者同时存在时以请求头为准。对于 fetch() 和 XHR,请使用请求头;X-Api-Version 已被 CORS 允许并 在响应中暴露,因此你可以读回实际应用了哪个版本。
校验
格式错误的值会返回 400 Bad Request,而不是悄悄回落:
{
"error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}该值必须是 YYYY-MM-DD 形式的真实日历日期。格式正确但超出支持范围的日期会被夹取而非拒绝:早于基线 的解析为基线,晚于最新变更的解析为最新行为。
缓存
响应体可能因版本而异的响应会带上 Vary: X-Api-Version,这样你的集成前面的共享缓存或 CDN 就会把这些 版本区分开。任何日期都相同的响应不带 Vary,从而让缓存为你的所有调用方只保留一条记录,而不是每个 日期一条。如果你自己缓存 API 响应,请对带该响应头的端点,把兼容性日期纳入缓存键。
什么算破坏性变更
会获得日期并出现在变更日志中的变更:
- 删除或重命名响应中的字段
- 改变现有字段的类型或结构
- 把可选字段变为必填,或把可省略字段变为始终存在
- 改变现有取值的含义
- 移除某个端点或改变其语义
不带版本发布的变更,因为它们不会破坏一个正确的客户端:
- 新增一个端点
- 新增一个可选的请求参数
- 在响应中新增一个字段
- 在你只做读取的枚举中新增一个取值
- 使行为与文档保持一致的缺陷修复
请让你的集成忽略未知的响应字段。新增性的变更会到达每一个版本,包括你的版本。