Версии и съвместимост

API има една основна версия, /v1, и тя само се разширява. Интеграция, написана днес, продължава да работи, докато се появяват нови възможности: нищо, на което тя разчита, не се преименува, не се премахва и не получава ново значение.

Номерът на версията

API има номер на версията, например 1.62.0. Той се променя с всяко издание:

• второстепенният номер – когато се добавя нещо: операция, поле, събитие;
• номерът на корекция – когато се поправя описание или текст на съобщение и нищо друго не се променя.

Версията, която обслужва даден адрес, може да прочетете по всяко време:

GET /v1/health също има version, но това е версията на изданието на Sursa, което обслужва адреса, а не версията на API.

Не избирате второстепенна версия: всяка заявка се обслужва от текущата. Благодарение на правилата по-долу това е безопасно.

Какво може да се промени в /v1

Тези промени може да дойдат във всяка второстепенна версия. Напишете интеграцията си така, че да не я нарушат:

• Нови операции.
• Нови незадължителни параметри и полета в заявките. Заявките без тях работят както преди.
• Нови полета в отговорите, обектите и събитията.
• Нови стойности на изброяванията в отговорите, например нов статус на карта или нов тип събитие.
• Нови кодове на грешки и нови заглавки на отговорите.
• По-малко строги лимити: по-голяма максимална дължина, по-широк диапазон.
• Преформулирани текстове message на грешките и преформулирани описания.

Какво трябва да понася кодът ви

• Пренебрегвайте полетата, които не познавате. Не допускайте грешка, когато отговорът има повече полета от очакваното, и не използвайте строги схеми, които ги отхвърлят.
• Приемайте стойности на изброявания, които не познавате. Всяко изброяване в отговор може да се разшири. Третирайте непозната стойност като „друго“, а не като грешка.
• Пропускайте типовете събития, които не познавате – и в уебхуковете, и в потоците.
• Обработвайте непознатите кодове на грешки по HTTP статуса им: вж. Грешки.
• Не разчитайте на реда на полетата в JSON обектите, нито на точния текст на съобщенията.

Какво никога не се променя в /v1

• Път, параметър, поле или стойност на изброяване никога не се преименува и не се премахва.
• Типът на поле никога не се променя и полето никога не получава ново значение, например нови мерни единици.
• Заявка, която се приема днес, няма да бъде отхвърлена по-късно.
• Кодът на статуса при успешен отговор остава същият.
• Кодовете на грешки запазват значението си, а полето detail в отговорите с грешка запазва формата си.
• Типовете събития никога не се преименуват и не се премахват, а тяхното data само получава нови полета.

Несъвместими промени

Ако някога се наложи несъвместима промяна, тя се издава като нова основна версия, например /v2, до /v1. /v1 продължава да работи без промяна и двете версии работят паралелно.

Когато даден маршрут предстои да бъде спрян:

1. Той се отбелязва като deprecated в спецификацията и се вписва в дневника на промените с датата, на която ще бъде изключен.
2. Отговорите му съдържат заглавките Deprecation: true и Sunset: <date>.
3. Той продължава да работи поне 180 дни след обявяването. Организациите, чиито API ключове го използват, се уведомяват писмено поне 90 дни предварително.
4. След датата на спиране той отговаря с 410 и кода api.gone още 90 дни.

Следете за заглавката Deprecation в дневниците или в мониторинга си: тя е най-ранният сигнал, че маршрут, който използвате, ще бъде премахнат.

Как да сте в течение

Дневникът на промените на този портал описва всяко издание – какво е добавено и какво е обявено за остаряло. Преди да обновите собствената си интеграция, сравнете кода ѝ със записите след версията, спрямо която сте я създали.