API-versionering
AstroAPI versioneert breaking changes met een compatibiliteitsdatum in plaats van een versienummer in de URL. De endpointpaden veranderen nooit; u zet een datum vast en blijft precies het gedrag ontvangen dat op die datum gold.
Uw versie
Stuur de compatibiliteitsdatum waartegen u hebt gebouwd mee in de X-Api-Version header:
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01Een response die door een compatibiliteitsdatum is gevormd, vertelt u welke:
X-Api-Version: 2026-01-01
Vary: X-Api-VersionEndpoints waarvan de uitvoer niet van de versie afhangt, laten beide headers weg. GET /api/modules geeft op elke datum hetzelfde antwoord, dus er valt niets te melden en niets voor een cache om apart te houden. Stuurt u expliciet een X-Api-Version, dan wordt die op elk endpoint teruggekaatst, zodat u altijd kunt bevestigen dat een waarde is geaccepteerd.
Om terug te lezen naar welke versie uw organisatie oplost, gebruikt u GET /api/org/api-version; de effectiveApiVersion daarvan is de datum die geldt wanneer een request geen eigen header draagt.
Stuurt u geen header mee, dan gebruiken requests de vastgezette versie van uw organisatie, en als u er geen hebt vastgezet, de baseline van 2026-01-01. Nieuw gedrag wordt nooit automatisch op u toegepast — een integratie die vandaag geschreven wordt, blijft ongewijzigd werken, wat we later ook uitbrengen.
Changelog
Elke breaking change staat hier met de datum waarop hij van kracht wordt. Een datum vastzetten geeft u elke wijziging op of vóór die datum.
| Datum | Wijziging |
|---|---|
2026-09-03 | aspects op POST /api/calc/transit is gegroepeerd: één entry per transiterende planeet, aspect en natale planeet, met de interpretatietekst één keer en elke passage van de periode onder occurrences. Voorheen één entry per passage, elk met dezelfde tekst. Zie Transits. |
2026-09-10 | Elk punt op POST /api/calc/natal draagt declination (graden, noord positief) en outOfBounds (voorbij de maximale declinatie van de Zon voor die datum). Voorheen was geen van beide velden aanwezig. Zie Declinaties. |
De baseline 2026-01-01 is de oudste versie die we serveren. Een eerdere datum vastzetten wordt geaccepteerd en lost op naar de baseline.
Uw organisatie vastzetten
In plaats van bij elke aanroep een header mee te sturen, zet u uw organisatie één keer vast. Alle requests zonder versie gebruiken dan die 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" }
}
}'Lees de huidige pin terug, samen met het bereik waaruit u kunt kiezen:
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"
}
}
}Stuur "apiVersion": null om de pin te wissen en terug te vallen op de baseline.
Veilig upgraden
De header wint altijd van de organisatiepin, en dat maakt een veilige uitrol mogelijk:
- Lees de changelog hierboven en controleer welke wijzigingen tussen uw huidige datum en de nieuwe vallen.
- Stuur de nieuwe datum mee in
X-Api-Versionop een paar requests, of in uw staging-omgeving, en verifieer de responses. - Als u tevreden bent, zet u uw organisatie vast op de nieuwe datum en laat u de header weer weg.
Omdat de header de pin per request overschrijft, kunt u het ook omgekeerd doen: uw organisatie vooruit vastzetten en tijdelijk een oudere datum meesturen vanuit een dienst die u nog niet hebt gemigreerd.
Browser- en embedclients
Contexten die geen requestheaders kunnen zetten — <img>-, <iframe>- en <script>-embeds, ondertekende chart-URL's — accepteren de datum in plaats daarvan als queryparameter:
https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...De header heeft voorrang als beide aanwezig zijn. Gebruik voor fetch() en XHR de header; X-Api-Version is toegestaan door CORS en wordt op responses blootgesteld, zodat u kunt teruglezen welke versie is toegepast.
Validatie
Een onjuist opgemaakte waarde geeft 400 Bad Request in plaats van stilletjes terug te vallen:
{
"error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}De waarde moet een echte kalenderdatum in YYYY-MM-DD-vorm zijn. Een correct opgemaakte datum buiten het ondersteunde bereik wordt begrensd in plaats van afgewezen: eerder dan de baseline lost op naar de baseline, later dan de nieuwste wijziging lost op naar het nieuwste gedrag.
Caching
Responses waarvan de inhoud per versie kan verschillen, zijn gemarkeerd met Vary: X-Api-Version, zodat een gedeelde cache of CDN vóór uw integratie die versies apart houdt. Responses die op elke datum hetzelfde zijn, dragen geen Vary, waardoor een cache één entry voor al uw bellers kan serveren in plaats van één per datum. Cachet u zelf API-responses, neem dan de compatibiliteitsdatum op in de cachesleutel voor de endpoints die de header dragen.
Wat telt als een breaking change
Wijzigingen die een datum krijgen en in de changelog verschijnen:
- Een veld uit een response verwijderen of hernoemen
- Het type of de vorm van een bestaand veld wijzigen
- Een optioneel veld verplicht maken, of een weggelaten veld altijd aanwezig
- De betekenis van een bestaande waarde wijzigen
- Een endpoint verwijderen of zijn semantiek wijzigen
Wijzigingen die zonder versie uitgaan, omdat ze een correcte client niet kunnen breken:
- Een nieuw endpoint toevoegen
- Een nieuwe optionele requestparameter toevoegen
- Een nieuw veld aan een response toevoegen
- Een nieuwe waarde toevoegen aan een enum die u alleen leest
- Bugfixes die het gedrag in lijn brengen met de documentatie
Schrijf uw integratie zo dat onbekende responsevelden worden genegeerd. Additieve wijzigingen komen op elke versie aan, ook op de uwe.