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 がグループ化されました。トランジット天体・アスペクト・出生天体の組み合わせごとに 1 エントリとなり、解釈テキストは 1 回だけ、その期間中の各通過は occurrences の下に入ります。以前は通過ごとに 1 エントリで、それぞれが同じテキストを繰り返していました。トランジットを参照してください。 |
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 が 付かないので、キャッシュは日付ごとではなく、すべての呼び出し元に対して 1 つのエントリを提供できます。 API レスポンスを自分でキャッシュする場合は、ヘッダーを持つエンドポイントについて、互換性日付を キャッシュキーに含めてください。
何が破壊的変更にあたるか
日付が割り当てられ、変更履歴に載る変更:
- レスポンスからフィールドを削除、または名前を変更する
- 既存フィールドの型や形を変更する
- 任意フィールドを必須にする、または省略されうるフィールドを常に存在させる
- 既存の値の意味を変更する
- エンドポイントを削除する、またはその意味を変更する
バージョンなしでリリースされる変更(正しいクライアントを壊しえないため):
- 新しいエンドポイントの追加
- 新しい任意リクエストパラメータの追加
- レスポンスへの新しいフィールドの追加
- 読み取るだけの列挙型への新しい値の追加
- 挙動をドキュメントに合わせるバグ修正
未知のレスポンスフィールドを無視するように統合を書いてください。追加的な変更は、あなたのバージョンを 含むすべてのバージョンに届きます。