Versionamento

L’API AstroWay utilizza il versioning tramite URL: la versione è specificata nel percorso della richiesta. Questo è più semplice del versioning basato su header ed è ben cacheabile dai proxy.

https://api.astroway.info/v1/chart

SemVer per l’API

Aderiamo alla semantica di semver.org:

• MAJOR (v1 → v2): modifiche che introducono rotture (breaking changes). La vecchia versione continua a funzionare per almeno 12 mesi dopo il rilascio della nuova.
• MINOR: nuovi endpoint, nuovi campi opzionali. Obbligatoriamente retrocompatibile.
• PATCH: correzioni di bug, miglioramenti della precisione. Visibile tramite l’header X-Api-Version: 1.12.3 nella risposta.

Cosa non è considerato una breaking change

• Aggiunta di un nuovo endpoint
• Aggiunta di un nuovo campo opzionale nel request body
• Aggiunta di un nuovo campo nella risposta
• Chiarimento del testo dei messaggi di errore (i codici code rimangono stabili)
• Modifiche alla precisione dei calcoli entro i limiti dichiarati di ±1” (pianeti) / ±1’ (case)
• Aumento del rate limit o del credit budget nel tuo piano

Questo significa: il tuo codice non deve bloccarsi quando viene aggiunto un nuovo campo nella risposta. Parsa solo ciò di cui hai bisogno e ignora il resto.

Cosa è una breaking change (solo in una major release)

• Eliminazione o ridenominazione di un endpoint
• Eliminazione o ridenominazione di un campo nella risposta
• Modifica del tipo di un campo (ad esempio, number → string)
• Modifica della semantica di un campo (che denota lo stesso nome)
• Modifica del code in una risposta di errore
• Inasprimento della validazione che potrebbe invalidare richieste precedentemente valide

Changelog

Tutte le modifiche sono nel Changelog. Le minor release avvengono ogni 2–4 settimane, le patch non appena sono pronte.

Iscriviti agli aggiornamenti:

• RSS: https://api.astroway.info/changelog/rss.xml
• Email: Settings → Notifications → Product updates nella dashboard

Deprecation policy

Quando un campo o un endpoint diventa deprecato:

1. Annunciamo nel changelog + notifica via email
2. Nella risposta appare l’header Deprecation: Sun, 01 Nov 2026 00:00:00 GMT (standard RFC 8594)
3. L’API deprecata continua a funzionare per almeno 12 mesi
4. Eliminazione: solo nella successiva major release