# Версіонування

AstroWay API використовує **URL versioning**: версія прописана в шляху запиту. Це простіше за header-based і добре кешується проксями.

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

## SemVer для API

Ми дотримуємось семантики [semver.org](https://semver.org/):

- **MAJOR** (`v1` → `v2`) — ламаючі зміни. Стара версія продовжує працювати щонайменше 12 місяців після релізу нової.
- **MINOR** — нові ендпоінти, нові опціональні поля. Обов'язково сумісно.
- **PATCH** — баг-фікси, уточнення точності. Видно через header `X-Api-Version: 1.12.3` у відповіді.

## Що **не** вважається breaking change

- Додавання нового ендпоінту
- Додавання нового опціонального поля в request body
- Додавання нового поля у відповідь
- Уточнення тексту error-повідомлень (коди `code` залишаються стабільними)
- Зміни точності розрахунків у межах задекларованих ±1" (планети) / ±1' (будинки)
- Збільшення rate limit або credit budget у твоєму плані

Це означає: твій код **не має** падати при додаванні нового поля у відповіді. Парси тільки те, що тобі потрібно, ігноруй решту.

## Що **є** breaking change (тільки в мажорному релізі)

- Видалення або перейменування ендпоінту
- Видалення або перейменування поля у відповіді
- Зміна типу поля (наприклад, `number` → `string`)
- Зміна семантики поля (що позначає те саме ім'я)
- Зміна `code` в error-відповіді
- Ужорсточення валідації, що може зламати раніше валідні запити

## Changelog

Усі зміни — у [Changelog](/changelog/). Мінорні релізи — кожні 2–4 тижні, патчі — по мірі готовності.

Підписатись на оновлення:
- RSS: `https://api.astroway.info/changelog/rss.xml`
- Email: `Settings → Notifications → Product updates` у [dashboard](https://api.astroway.info/dashboard/settings)

## Deprecation policy

Коли поле або ендпоінт стає deprecated:
1. Об'являємо в changelog + email-notice
2. У відповіді з'являється header `Deprecation: Sun, 01 Nov 2026 00:00:00 GMT` (стандарт [RFC 8594](https://datatracker.ietf.org/doc/html/rfc8594))
3. Deprecated API продовжує працювати **мінімум 12 місяців**
4. Видалення — тільки в наступному мажорному релізі