Wersje i zgodność

API ma jedną wersję główną, /v1, i ta wersja tylko się rozrasta. Integracja napisana dziś działa dalej, gdy pojawiają się nowe funkcje: nic, na czym polega, nie zmienia nazwy, nie znika ani nie zyskuje nowego znaczenia.

Numer wersji

API ma numer wersji, np. 1.62.0. Zmienia się on z każdym wydaniem:

• numer wersji pomocniczej, gdy coś zostaje dodane: operacja, pole, zdarzenie;
• numer poprawki, gdy poprawiany jest opis lub tekst komunikatu i nic poza tym się nie zmienia.

Wersję obsługiwaną pod danym adresem możesz odczytać w każdej chwili:

GET /v1/health również zwraca version, ale jest to wersja wydania Sursy, które obsługuje dany adres, a nie wersja API.

Nie wybierasz wersji pomocniczej: każde żądanie jest obsługiwane przez bieżącą. Dzięki poniższym zasadom jest to bezpieczne.

Co może się zmienić w /v1

Te zmiany mogą pojawić się w każdej wersji pomocniczej. Napisz integrację tak, aby jej nie zaszkodziły:

• Nowe operacje.
• Nowe opcjonalne parametry i pola żądań. Żądania bez nich działają tak jak wcześniej.
• Nowe pola w odpowiedziach, obiektach i zdarzeniach.
• Nowe wartości wyliczeń w odpowiedziach, np. nowy status karty lub nowy typ zdarzenia.
• Nowe kody błędów i nowe nagłówki odpowiedzi.
• Limity, które stają się mniej rygorystyczne: większa maksymalna długość, szerszy zakres.
• Przeredagowane teksty message błędów i przeredagowane opisy.

Co Twój kod musi tolerować

• Ignoruj pola, których nie znasz. Nie zgłaszaj błędu, gdy odpowiedź ma więcej pól, niż oczekujesz, i nie używaj ścisłych schematów, które je odrzucają.
• Akceptuj nieznane wartości wyliczeń. Każde wyliczenie w odpowiedzi może się rozrastać. Nieznaną wartość traktuj jako „inną”, a nie jako błąd.
• Pomijaj nieznane typy zdarzeń, zarówno w webhookach, jak i w strumieniach.
• Obsługuj nieznane kody błędów według ich statusu HTTP: zob. Błędy.
• Nie polegaj na kolejności pól w obiektach JSON ani na dokładnym tekście komunikatów.

Co nigdy nie zmienia się w /v1

• Żadna ścieżka, parametr, pole ani wartość wyliczenia nigdy nie zmienia nazwy i nie jest usuwana.
• Typ pola nigdy się nie zmienia, a pole nigdy nie zyskuje nowego znaczenia, np. nowych jednostek.
• Żądanie akceptowane dziś nie zostanie później odrzucone.
• Kod statusu pomyślnej odpowiedzi pozostaje taki sam.
• Kody błędów zachowują swoje znaczenie, a pole detail odpowiedzi z błędem zachowuje swoją formę.
• Typy zdarzeń nigdy nie zmieniają nazwy ani nie są usuwane, a ich data może jedynie zyskiwać nowe pola.

Zmiany niezgodne wstecz

Jeśli kiedykolwiek będzie potrzebna zmiana niezgodna wstecz, zostanie wydana jako nowa wersja główna, np. /v2, obok /v1. /v1 działa dalej bez zmian, a obie wersje działają równolegle.

Gdy trasa ma zostać wycofana:

1. Zostaje oznaczona jako deprecated w specyfikacji i wymieniona w dzienniku zmian z datą wyłączenia.
2. Jej odpowiedzi zawierają nagłówki Deprecation: true i Sunset: <date>.
3. Działa przez co najmniej 180 dni od ogłoszenia. Organizacje, których klucze API z niej korzystają, są powiadamiane na piśmie co najmniej 90 dni wcześniej.
4. Po dacie wycofania przez kolejne 90 dni odpowiada 410 z kodem api.gone.

Obserwuj nagłówek Deprecation w dziennikach lub monitoringu: to najwcześniejszy sygnał, że trasa, z której korzystasz, zniknie.

Jak być na bieżąco

Dziennik zmian tego portalu wymienia każde wydanie wraz z tym, co dodano i co oznaczono jako przestarzałe. Zanim zaktualizujesz własną integrację, porównaj jej kod z wpisami od wersji, dla której ją zbudowano.