Spis treści
Dlaczego wersjonowanie jest konieczne
Interfejsy API rozwijają się wraz ze zmieniającymi się wymaganiami biznesowymi, co nieuchronnie prowadzi do sytuacji, w których nowa wersja kontraktu nie jest w pełni kompatybilna z poprzednią. Wersjonowanie pozwala wprowadzać takie zmiany bez natychmiastowego zrywania integracji istniejących konsumentów interfejsu.
Podstawowe strategie wersjonowania
Najczęściej spotykane podejścia obejmują wersjonowanie poprzez ścieżkę URL (na przykład /v1/, /v2/), wersjonowanie za pomocą nagłówków HTTP oraz wersjonowanie na poziomie poszczególnych pól w odpowiedzi API. Każde z tych podejść wiąże się z innym poziomem złożoności po stronie zarówno dostawcy, jak i konsumenta interfejsu.
Wersjonowanie w ścieżce URL jest najbardziej czytelne dla konsumentów API i najłatwiejsze do wdrożenia w warstwie routingu, jednak prowadzi do utrzymywania równolegle wielu pełnych wersji tego samego zasobu. Wersjonowanie nagłówkami pozwala zachować jeden adres zasobu, kosztem mniejszej przejrzystości dla osób integrujących się z API po raz pierwszy.
Proces wycofywania starszych wersji
Wycofanie starszej wersji interfejsu wymaga zaplanowanego procesu komunikacji z konsumentami API, obejmującego zazwyczaj okres przejściowy, w którym stara i nowa wersja działają równolegle. W tym czasie starsza wersja bywa oznaczana nagłówkiem informującym o planowanej dacie wycofania (deprecation notice).
Praktyka pokazuje, że zbyt krótki okres przejściowy prowadzi do presji czasowej po stronie zespołów integrujących się z API, natomiast zbyt długi — do konieczności utrzymywania wielu wersji jednocześnie, co zwiększa koszt operacyjny po stronie dostawcy interfejsu.
Pytania i odpowiedzi
Czy każda zmiana w API wymaga nowej wersji?
Nie — zmiany kompatybilne wstecznie, takie jak dodanie nowego, opcjonalnego pola w odpowiedzi, zazwyczaj nie wymagają wprowadzenia nowej wersji interfejsu. Nowa wersja jest konieczna przy zmianach niekompatybilnych, np. usunięciu pola lub zmianie jego typu.
Jak długo powinna być utrzymywana starsza wersja API?
Okres utrzymania zależy od liczby i charakteru konsumentów interfejsu. W programach partnerskich okres ten jest zazwyczaj ustalany w ramach umowy lub polityki wsparcia technicznego dostawcy API.