Główne podejścia do wersjonowania
W dokumentacjach dotyczących projektowania API wyróżnia się kilka podstawowych strategii wersjonowania: wersjonowanie w ścieżce URL (np. /v1/zasob), wersjonowanie za pomocą nagłówków żądania (np. nagłówek Accept-Version), wersjonowanie poprzez parametr zapytania oraz wersjonowanie oparte na negocjacji treści (content negotiation) z wykorzystaniem nagłówka Accept.
Każde z tych podejść niesie odmienne konsekwencje dla struktury bramki API — wersjonowanie w URL wymaga jawnego routingu na poziomie ścieżki, natomiast wersjonowanie nagłówkowe przenosi logikę routingu do warstwy analizy metadanych żądania.
Zgodność wsteczna a cykl życia wersji
Zarządzanie cyklem życia interfejsów obejmuje planowanie momentu wycofania starszych wersji API (deprecation) oraz komunikowanie tego faktu konsumentom API z odpowiednim wyprzedzeniem. Bramki API często udostępniają mechanizmy oznaczania endpointów jako przestarzałych poprzez dedykowane nagłówki odpowiedzi, informujące klientów o planowanym terminie wycofania danej wersji.
Kryteria wyboru strategii
Wybór konkretnego podejścia do wersjonowania zależy od charakterystyki konsumentów API, liczby jednocześnie wspieranych wersji oraz preferowanego stylu dokumentacji technicznej. W środowiskach enterprise, gdzie z API korzysta wielu zewnętrznych partnerów, istotna jest przewidywalność i jasna komunikacja zmian w interfejsie.
Czy wersjonowanie w URL jest lepsze niż w nagłówkach?
Obie metody mają swoje zastosowania — wersjonowanie w URL jest bardziej czytelne i łatwiejsze do testowania, natomiast wersjonowanie w nagłówkach pozwala zachować czystszą strukturę adresów zasobów.
Jak długo należy utrzymywać starą wersję API?
Okres utrzymania zależy od polityki organizacji oraz liczby aktywnych konsumentów korzystających ze starszej wersji; typowe okresy wsparcia opisywane w dokumentacjach wynoszą od kilku miesięcy do kilku lat.