API-Versionierung
AstroAPI versioniert Breaking Changes mit einem Kompatibilitätsdatum statt mit einer Versionsnummer in der URL. Die Endpunktpfade ändern sich nie; Sie legen ein Datum fest und erhalten weiterhin genau das Verhalten, das an diesem Datum aktuell war.
Ihre Version
Senden Sie das Kompatibilitätsdatum, gegen das Sie entwickelt haben, im Header X-Api-Version:
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01Eine Antwort, die von einem Kompatibilitätsdatum geformt wurde, sagt Ihnen, von welchem:
X-Api-Version: 2026-01-01
Vary: X-Api-VersionEndpunkte, deren Ausgabe nicht von der Version abhängt, lassen beide Header weg. GET /api/modules liefert an jedem Datum denselben Body, also gibt es nichts zu melden und nichts, was ein Cache auseinanderhalten müsste. Senden Sie ein explizites X-Api-Version, wird es auf jedem Endpunkt zurückgespiegelt, sodass Sie stets bestätigen können, dass ein Wert akzeptiert wurde.
Um zurückzulesen, auf welche Version Ihre Organisation auflöst, verwenden Sie GET /api/org/api-version; dessen effectiveApiVersion ist das Datum, das gilt, wenn eine Anfrage keinen eigenen Header trägt.
Senden Sie keinen Header, verwenden Anfragen die festgelegte Version Ihrer Organisation, und wenn Sie keine festgelegt haben, die Baseline 2026-01-01. Neues Verhalten wird Ihnen nie automatisch angewendet — eine heute geschriebene Integration funktioniert unverändert weiter, ganz gleich, was wir später ausliefern.
Changelog
Jede Breaking Change ist hier mit dem Datum aufgeführt, an dem sie in Kraft tritt. Ein Datum festzulegen gibt Ihnen jede Änderung an oder vor diesem Datum.
| Datum | Änderung |
|---|---|
2026-09-03 | aspects auf POST /api/calc/transit ist gruppiert: ein Eintrag pro transitierendem Planeten, Aspekt und Radixplaneten, mit dem Deutungstext einmal und jedem Durchgang des Zeitraums unter occurrences. Zuvor ein Eintrag pro Durchgang, jeder mit demselben Text. Siehe Transite. |
2026-09-10 | Jeder Punkt auf POST /api/calc/natal trägt declination (Grad, Norden positiv) und outOfBounds (jenseits der maximalen Deklination der Sonne für dieses Datum). Zuvor war keines der beiden Felder vorhanden. Siehe Deklinationen. |
Die Baseline 2026-01-01 ist die älteste Version, die wir ausliefern. Ein früheres Datum festzulegen wird akzeptiert und löst auf die Baseline auf.
Ihre Organisation festlegen
Statt jedem Aufruf einen Header hinzuzufügen, legen Sie Ihre Organisation einmal fest. Alle Anfragen ohne Version verwenden dann dieses Datum.
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" }
}
}'Lesen Sie die aktuelle Festlegung zurück, zusammen mit dem Bereich, aus dem Sie wählen können:
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"
}
}
}Senden Sie "apiVersion": null, um die Festlegung zu löschen und auf die Baseline zurückzufallen.
Sicher aktualisieren
Der Header gewinnt immer gegen die Organisationsfestlegung, was einen sicheren Rollout ermöglicht:
- Lesen Sie das Changelog oben und prüfen Sie, welche Änderungen zwischen Ihrem aktuellen und dem neuen Datum liegen.
- Senden Sie das neue Datum in
X-Api-Versionbei einigen Anfragen oder in Ihrer Staging-Umgebung und überprüfen Sie die Antworten. - Wenn Sie zufrieden sind, legen Sie Ihre Organisation auf das neue Datum fest und lassen den Header wieder weg.
Weil der Header die Festlegung pro Anfrage überschreibt, geht auch der umgekehrte Weg: Sie legen Ihre Organisation vorwärts fest und senden vorübergehend ein älteres Datum aus einem Dienst, den Sie noch nicht migriert haben.
Browser- und Embed-Clients
Kontexte, die keine Request-Header setzen können — <img>-, <iframe>- und <script>-Einbettungen, signierte Chart-URLs — akzeptieren das Datum stattdessen als Query-Parameter:
https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...Der Header hat Vorrang, wenn beide vorhanden sind. Für fetch() und XHR verwenden Sie den Header; X-Api-Version ist per CORS erlaubt und wird auf Antworten offengelegt, sodass Sie zurücklesen können, welche Version angewendet wurde.
Validierung
Ein fehlerhafter Wert liefert 400 Bad Request, statt still zurückzufallen:
{
"error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}Der Wert muss ein echtes Kalenderdatum in der Form YYYY-MM-DD sein. Ein wohlgeformtes Datum außerhalb des unterstützten Bereichs wird begrenzt statt abgelehnt: früher als die Baseline löst auf die Baseline auf, später als die neueste Änderung auf das neueste Verhalten.
Caching
Antworten, deren Body sich je Version unterscheiden kann, sind mit Vary: X-Api-Version markiert, sodass ein gemeinsamer Cache oder ein CDN vor Ihrer Integration diese Versionen auseinanderhält. Antworten, die an jedem Datum gleich sind, tragen kein Vary, wodurch ein Cache einen Eintrag für alle Ihre Aufrufer statt einen pro Datum ausliefern kann. Cachen Sie API-Antworten selbst, nehmen Sie das Kompatibilitätsdatum für die Endpunkte, die den Header tragen, in den Cache-Schlüssel auf.
Was als Breaking Change gilt
Änderungen, die ein Datum erhalten und im Changelog erscheinen:
- Ein Feld in einer Antwort entfernen oder umbenennen
- Typ oder Form eines bestehenden Feldes ändern
- Ein optionales Feld verpflichtend machen oder ein weggelassenes Feld immer vorhanden
- Die Bedeutung eines bestehenden Wertes ändern
- Einen Endpunkt entfernen oder seine Semantik ändern
Änderungen, die ohne Version ausgeliefert werden, weil sie einen korrekten Client nicht brechen können:
- Einen neuen Endpunkt hinzufügen
- Einen neuen optionalen Request-Parameter hinzufügen
- Ein neues Feld zu einer Antwort hinzufügen
- Einen neuen Wert zu einem Enum hinzufügen, das Sie nur lesen
- Bugfixes, die das Verhalten mit der Dokumentation in Einklang bringen
Schreiben Sie Ihre Integration so, dass unbekannte Antwortfelder ignoriert werden. Additive Änderungen erreichen jede Version, auch Ihre.