Верзије и компатибилност

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. После датума гашења још 90 дана одговара са 410 и кодом api.gone.

Пратите заглавље Deprecation у својим логовима или систему надзора: то је најранији сигнал да путања коју користите нестаје.

Како да будете у току

Дневник измена овог портала наводи свако издање, са оним што је додато и оним што је проглашено застарелим. Пре него што надоградите своју интеграцију, упоредите њен код са записима од верзије за коју сте је направили.