Dziennik zmian i deprecacje
To miejsce, w którym ogłaszamy zmiany w Commerce API oraz zapowiadamy wycofywane pola i operacje (deprecacje). Zaglądaj tu przed aktualizacją integracji.
Dziennik zapełni się wpisami wraz z udostępnianiem API. Na starcie może być pusty — to znaczy, że nie ma jeszcze ogłoszonych zmian ani deprecacji.
Polityka wersjonowania
Kontrakt API jest wersjonowany, a zmiany dzielimy na dwie kategorie:
- Zmiany dodające (kompatybilne) — nowe, opcjonalne pola, nowe operacje lub nowe wartości enumów, które nie łamią istniejących integracji. Wprowadzamy je w bieżącej wersji API. Twój kod powinien ignorować nieznane pola, aby był na nie odporny.
- Zmiany łamiące (breaking) — usunięcie lub zmiana znaczenia pola, zmiana
typu, zaostrzenie wymagalności. Takich zmian nie wprowadzamy w istniejącej
wersji — trafiają do nowej wersji (np.
/v2), a poprzednia pozostaje wspierana przez ogłoszony okres.
Zgodne vs łamiące
| Rodzaj zmiany | Przykład | Gdzie trafia |
|---|---|---|
| Dodająca (kompatybilna) | Nowe opcjonalne pole w odpowiedzi | Bieżąca wersja |
| Dodająca (kompatybilna) | Nowa operacja lub nowy webhook | Bieżąca wersja |
| Łamiąca (breaking) | Usunięcie pola lub zmiana typu | Nowa wersja (/v2) |
| Łamiąca (breaking) | Pole opcjonalne staje się wymagane | Nowa wersja (/v2) |
Deprecacje
Wycofywane pola i operacje oznaczamy z wyprzedzeniem. Dla każdej deprecacji podamy: czego dotyczy, datę zakończenia wsparcia oraz zalecaną ścieżkę migracji. Pole oznaczone jako deprecated działa do ogłoszonego terminu — zaplanuj migrację zanim ten termin nadejdzie.
Jak śledzić zmiany
Aktualizacje ogłaszamy na tej stronie. Zmiany dotyczące samego kontraktu wiążemy z jego wersją i sumą kontrolną — patrz Pobierz kontrakt API. W razie pytań o wpływ konkretnej zmiany na Twoją integrację skontaktuj się z nami przez Wsparcie.