Versionamento dell'API
AstroAPI versiona le modifiche incompatibili con una data di compatibilità anziché con un numero di versione nell'URL. I percorsi degli endpoint non cambiano mai; voi fissate una data e continuate a ricevere esattamente il comportamento in vigore a quella data.
La vostra versione
Inviate la data di compatibilità su cui avete sviluppato nell'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-01Una risposta modellata da una data di compatibilità vi dice quale:
X-Api-Version: 2026-01-01
Vary: X-Api-VersionGli endpoint il cui output non dipende dalla versione omettono entrambi gli header. GET /api/modules restituisce lo stesso corpo a ogni data, quindi non c'è nulla da segnalare e nulla che una cache debba tenere separato. Se inviate un X-Api-Version esplicito, vi viene restituito su qualsiasi endpoint, così potete sempre confermare che un valore è stato accettato.
Per rileggere la versione a cui si risolve la vostra organizzazione, usate GET /api/org/api-version; il suo effectiveApiVersion è la data che si applica quando una richiesta non porta un header proprio.
Se non inviate alcun header, le richieste usano la versione fissata della vostra organizzazione e, se non ne avete fissata nessuna, la baseline 2026-01-01. Il nuovo comportamento non vi viene mai applicato automaticamente: un'integrazione scritta oggi continua a funzionare invariata, qualunque cosa rilasciamo in seguito.
Changelog
Ogni modifica incompatibile è elencata qui con la data in cui entra in vigore. Fissare una data vi dà tutte le modifiche a quella data o precedenti.
| Data | Modifica |
|---|---|
2026-09-03 | aspects su POST /api/calc/transit è raggruppato: una voce per pianeta in transito, aspetto e pianeta natale, con il testo interpretativo una sola volta e ogni passaggio del periodo sotto occurrences. Prima una voce per passaggio, ciascuna con lo stesso testo. Vedi Transiti. |
2026-09-10 | Ogni punto di POST /api/calc/natal porta declination (gradi, nord positivo) e outOfBounds (oltre la declinazione massima del Sole per quella data). Prima nessuno dei due campi era presente. Vedi Declinazioni. |
La baseline 2026-01-01 è la versione più vecchia che serviamo. Fissare una data precedente è accettato e si risolve alla baseline.
Fissare la vostra organizzazione
Anziché aggiungere un header a ogni chiamata, fissate la vostra organizzazione una volta. Tutte le richieste senza versione useranno allora quella data.
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" }
}
}'Rileggete il valore fissato attuale, insieme all'intervallo fra cui potete scegliere:
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"
}
}
}Inviate "apiVersion": null per cancellare il valore fissato e tornare alla baseline.
Aggiornare in sicurezza
L'header vince sempre sul valore fissato dall'organizzazione, il che rende possibile un rollout sicuro:
- Leggete il changelog qui sopra e verificate quali modifiche cadono fra la vostra data attuale e quella nuova.
- Inviate la nuova data in
X-Api-Versionsu alcune richieste, o nel vostro ambiente di staging, e verificate le risposte. - Quando siete soddisfatti, fissate la vostra organizzazione alla nuova data e togliete di nuovo l'header.
Poiché l'header sovrascrive il valore fissato per singola richiesta, potete anche fare il contrario: fissare la vostra organizzazione in avanti e inviare temporaneamente una data più vecchia da un servizio che non avete ancora migrato.
Client browser e incorporamenti
I contesti che non possono impostare header di richiesta — incorporamenti <img>, <iframe> e <script>, URL di carta firmate — accettano invece la data come parametro di query:
https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...L'header ha la precedenza quando entrambi sono presenti. Per fetch() e XHR usate l'header; X-Api-Version è consentito da CORS ed esposto sulle risposte, così potete rileggere quale versione è stata applicata.
Validazione
Un valore malformato restituisce 400 Bad Request invece di ripiegare in silenzio:
{
"error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}Il valore deve essere una data di calendario reale nella forma YYYY-MM-DD. Una data ben formata al di fuori dell'intervallo supportato viene limitata anziché rifiutata: precedente alla baseline si risolve alla baseline, successiva alla modifica più recente si risolve al comportamento più recente.
Caching
Le risposte il cui corpo può differire per versione sono marcate Vary: X-Api-Version, così una cache condivisa o una CDN davanti alla vostra integrazione terrà separate quelle versioni. Le risposte uguali a ogni data non portano Vary, il che consente a una cache di servire una sola voce per tutti i vostri chiamanti anziché una per data. Se mettete in cache voi stessi le risposte dell'API, includete la data di compatibilità nella chiave di cache per gli endpoint che portano l'header.
Cosa conta come modifica incompatibile
Modifiche che ricevono una data e compaiono nel changelog:
- Rimuovere o rinominare un campo in una risposta
- Cambiare il tipo o la forma di un campo esistente
- Rendere obbligatorio un campo opzionale, o sempre presente un campo omesso
- Cambiare il significato di un valore esistente
- Rimuovere un endpoint o cambiarne la semantica
Modifiche che vengono rilasciate senza versione, perché non possono rompere un client corretto:
- Aggiungere un nuovo endpoint
- Aggiungere un nuovo parametro di richiesta opzionale
- Aggiungere un nuovo campo a una risposta
- Aggiungere un nuovo valore a un enum che voi soltanto leggete
- Correzioni di bug che allineano il comportamento alla documentazione
Scrivete la vostra integrazione in modo che ignori i campi di risposta sconosciuti. Le modifiche additive arrivano a ogni versione, compresa la vostra.