Skip to content

API 版本控制 ​

AstroAPI 用兼容性日期而非 URL 中的版本号来管理破坏性变更。端点路径永不改变;你固定一个日期, 就会一直收到该日期当时的行为。

你的版本 ​

在 X-Api-Version 请求头中发送你所依据的兼容性日期:

http
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01

由某个兼容性日期塑形的响应会告诉你是哪一个:

http
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-03POST /api/calc/transit 上的 aspects 已分组:每个行运行星、相位与本命行星的组合一条记录,解读文本只出现一次,该时段内的每次经过放在 occurrences 下。此前是每次经过一条记录,且各自重复相同文本。参见行运。
2026-09-10POST /api/calc/natal 上的每个天体点都带有 declination(度,北为正)和 outOfBounds(超出该日期太阳的最大赤纬)。此前这两个字段都不存在。参见赤纬。

基线 2026-01-01 是我们提供的最早版本。固定更早的日期会被接受,并解析为基线。

固定你的组织 ​

与其给每次调用都加一个请求头,不如把组织固定一次。此后所有未指定版本的请求都会使用该日期。

bash
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" }
    }
  }'

读回当前固定值,以及你可以选择的范围:

bash
curl "https://api.astroapi.cloud/api/org/api-version" \
  -H "X-Api-Key: your_api_key"
json
{
  "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 可清除固定值并回落到基线。

安全升级 ​

请求头总是胜过组织固定值,这使得安全上线成为可能:

  1. 阅读上面的变更日志,检查哪些变更落在你当前日期与新日期之间。
  2. 在少量请求上,或在你的预发布环境中,用 X-Api-Version 发送新日期并验证响应。
  3. 满意之后,把组织固定到新日期,并再次去掉请求头。

由于请求头会按请求覆盖固定值,你也可以反过来:把组织向前固定,同时从尚未迁移的服务里临时发送较旧 的日期。

浏览器与嵌入式客户端 ​

无法设置请求头的场景——<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,而不是悄悄回落:

json
{
  "error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}

该值必须是 YYYY-MM-DD 形式的真实日历日期。格式正确但超出支持范围的日期会被夹取而非拒绝:早于基线 的解析为基线,晚于最新变更的解析为最新行为。

缓存 ​

响应体可能因版本而异的响应会带上 Vary: X-Api-Version,这样你的集成前面的共享缓存或 CDN 就会把这些 版本区分开。任何日期都相同的响应不带 Vary,从而让缓存为你的所有调用方只保留一条记录,而不是每个 日期一条。如果你自己缓存 API 响应,请对带该响应头的端点,把兼容性日期纳入缓存键。

什么算破坏性变更 ​

会获得日期并出现在变更日志中的变更:

  • 删除或重命名响应中的字段
  • 改变现有字段的类型或结构
  • 把可选字段变为必填,或把可省略字段变为始终存在
  • 改变现有取值的含义
  • 移除某个端点或改变其语义

不带版本发布的变更,因为它们不会破坏一个正确的客户端:

  • 新增一个端点
  • 新增一个可选的请求参数
  • 在响应中新增一个字段
  • 在你只做读取的枚举中新增一个取值
  • 使行为与文档保持一致的缺陷修复

请让你的集成忽略未知的响应字段。新增性的变更会到达每一个版本,包括你的版本。

AstroAPI Documentation