Версионирование API
AstroAPI версионирует несовместимые изменения с помощью даты совместимости, а не номера версии в URL. Пути конечных точек никогда не меняются; вы закрепляете дату и продолжаете получать ровно то поведение, которое действовало на эту дату.
Ваша версия
Отправляйте дату совместимости, под которую вы разрабатывали, в заголовке X-Api-Version:
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01Ответ, сформированный датой совместимости, сообщает, какой именно:
X-Api-Version: 2026-01-01
Vary: X-Api-VersionКонечные точки, вывод которых не зависит от версии, оба заголовка опускают. GET /api/modules возвращает одно и то же тело на любую дату, поэтому сообщать нечего и кэшу нечего разделять. Отправьте явный X-Api-Version, и он вернётся вам на любой конечной точке, так что вы всегда можете убедиться, что значение принято.
Чтобы прочитать, к какой версии разрешается ваша организация, используйте GET /api/org/api-version; его effectiveApiVersion — это дата, которая применяется, когда запрос не несёт собственного заголовка.
Если вы не отправляете заголовок, запросы используют закреплённую версию вашей организации, а если вы не закрепили ни одной — базовую 2026-01-01. Новое поведение никогда не применяется к вам автоматически: интеграция, написанная сегодня, продолжит работать без изменений, что бы мы ни выпустили позже.
Журнал изменений
Каждое несовместимое изменение перечислено здесь с датой вступления в силу. Закрепление даты даёт вам все изменения на эту дату или ранее.
| Дата | Изменение |
|---|---|
2026-09-03 | aspects в POST /api/calc/transit сгруппированы: одна запись на транзитную планету, аспект и натальную планету, с текстом интерпретации один раз и каждым прохождением периода в occurrences. Раньше была одна запись на прохождение, и каждая повторяла текст. См. Транзиты. |
2026-09-10 | Каждая точка в POST /api/calc/natal несёт declination (градусы, север положительный) и outOfBounds (за пределами максимального склонения Солнца на эту дату). Раньше ни одного из этих полей не было. См. Склонения. |
Базовая версия 2026-01-01 — самая старая, которую мы обслуживаем. Закрепление более ранней даты принимается и разрешается в базовую.
Закрепление организации
Вместо того чтобы добавлять заголовок к каждому вызову, закрепите организацию один раз. Все запросы без версии будут тогда использовать эту дату.
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" }
}
}'Прочитайте текущее закрепление вместе с диапазоном, из которого можно выбирать:
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"
}
}
}Отправьте "apiVersion": null, чтобы снять закрепление и вернуться к базовой версии.
Безопасное обновление
Заголовок всегда побеждает закрепление организации, что делает возможным безопасное развёртывание:
- Прочитайте журнал выше и проверьте, какие изменения попадают между вашей текущей датой и новой.
- Отправьте новую дату в
X-Api-Versionна нескольких запросах или в тестовой среде и проверьте ответы. - Когда результат вас устроит, закрепите организацию на новой дате и снова уберите заголовок.
Поскольку заголовок переопределяет закрепление в каждом запросе, возможно и обратное: закрепить организацию вперёд и временно отправлять более раннюю дату из сервиса, который вы ещё не перевели.
Браузерные клиенты и встраивания
Контексты, которые не могут задавать заголовки запроса — встраивания <img>, <iframe> и <script>, подписанные URL карт, — принимают дату как параметр запроса:
https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...Заголовок имеет приоритет, когда присутствуют оба. Для fetch() и XHR используйте заголовок; X-Api-Version разрешён CORS и раскрывается в ответах, так что вы можете прочитать, какая версия была применена.
Проверка
Некорректное значение возвращает 400 Bad Request, а не молча откатывается:
{
"error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}Значение должно быть настоящей календарной датой в форме YYYY-MM-DD. Корректно оформленная дата вне поддерживаемого диапазона ограничивается, а не отклоняется: раньше базовой — разрешается в базовую, позже последнего изменения — в самое новое поведение.
Кэширование
Ответы, тело которых может различаться по версиям, помечаются Vary: X-Api-Version, так что общий кэш или CDN перед вашей интеграцией будет разделять эти версии. Ответы, одинаковые на любую дату, Vary не несут, что позволяет кэшу отдавать одну запись всем вашим клиентам вместо одной на дату. Если вы кэшируете ответы API сами, включайте дату совместимости в ключ кэша для тех конечных точек, которые несут заголовок.
Что считается несовместимым изменением
Изменения, которые получают дату и попадают в журнал:
- Удаление или переименование поля в ответе
- Изменение типа или формы существующего поля
- Превращение необязательного поля в обязательное или опускаемого — во всегда присутствующее
- Изменение смысла существующего значения
- Удаление конечной точки или изменение её семантики
Изменения, которые выходят без версии, потому что не могут сломать корректного клиента:
- Добавление новой конечной точки
- Добавление нового необязательного параметра запроса
- Добавление нового поля в ответ
- Добавление нового значения в перечисление, которое вы только читаете
- Исправления, приводящие поведение в соответствие с документацией
Пишите интеграцию так, чтобы она игнорировала неизвестные поля ответа. Аддитивные изменения приходят во все версии, включая вашу.