---
title: "Версіонування · API Reference: документація AOA API"
description: "Політика версіонування і застарівання (deprecation policy) API AOA: що змінюється без нової версії, заголовки Deprecation і Sunset, 90 днів до вимкнення."
canonical: "https://aoa.com.ua/docs/api-reference/versioning"
---

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

Політика версіонування і застарівання (deprecation policy) API AOA: що змінюється без нової версії, заголовки Deprecation і Sunset, 90 днів до вимкнення.

Версіонування: версія в шляху (/api/v1). Зміни, що ламають сумісність, виходять лише в новій версії. Кожна відповідь API несе заголовок Link з rel="deprecation" і rel="sunset", який веде на сторінку цієї політики. Застарілий ендпоінт додатково позначається заголовками Deprecation і Sunset (RFC 9745, RFC 8594) щонайменше за 90 днів до вимкнення, а дата вимкнення дублюється в документації.

Зараз актуальна версія `v1`, застарілих ендпоінтів немає.

## Що змінюється без нової версії

Ці зміни не ламають інтеграцію, тож виходять у `v1` без попередження. Розраховуйте на них у своєму коді:

- нові ендпоінти;
- нові поля у відповідях: невідомі поля варто ігнорувати;
- нові необовʼязкові параметри запиту;
- нові значення в переліках (статуси, коди помилок): обробляйте невідоме значення як загальний випадок.

## Що вимагає нової версії

| Зміна | Як виходить |
| --- | --- |
| Видалення або перейменування поля | Лише в новій версії |
| Зміна типу поля чи формату значення | Лише в новій версії |
| Новий обовʼязковий параметр | Лише в новій версії |
| Видалення ендпоінта | Застарівання, щонайменше 90 днів |

## Як ми позначаємо застарівання

Кожна відповідь API, зокрема помилки, несе заголовок `Link` на цю сторінку з `rel="deprecation"` і `rel="sunset"`. Без заголовка `Deprecation` він означає «ендпоінт не застарів, ось наша політика» (RFC 9745, розділ 3.1), тож інтеграція може знайти політику, не читаючи документацію:

```http
HTTP/1.1 200 OK
Link: </docs/api-reference/versioning>; rel="deprecation"; type="text/html", </docs/api-reference/versioning>; rel="sunset"; type="text/html"
```

Застарілий ендпоінт і далі працює, але кожна його відповідь несе заголовки `Deprecation` (RFC 9745, момент оголошення) і `Sunset` (RFC 8594, дата вимкнення), а `Link` з `rel="deprecation"` веде на цю сторінку. Між оголошенням і вимкненням щонайменше 90 днів; дата вимкнення також зʼявляється в документації ендпоінта.

```http
HTTP/1.1 200 OK
Deprecation: @1817078400
Sunset: Tue, 30 Nov 2027 00:00:00 GMT
Link: <https://aoa.com.ua/docs/api-reference/versioning>; rel="deprecation"
```

Порада: логуйте відповіді із заголовком `Deprecation` у своїй інтеграції, тоді зміна не застане зненацька.