api-versioning

Create and maintain API version changes. Use when adding breaking changes to API responses/requests, creating version change files, transforming data between versions, or handling backward compatibility.

1. Zdefiniuj schemat najnowszej wersji API w pliku shared/api/{zasób}/apiCustomer.ts używając Zod lub podobnej biblioteki walidacji. Określ wszystkie pola i ich typy dla bieżącej wersji.
2. Utwórz plik starego schematu w katalogu shared/api/{zasób}/previousVersions/ (np. apiCustomerV3.ts), opisując strukturę danych z poprzedniej wersji, którą chcesz obsługiwać.
3. Stwórz plik transformacji odpowiedzi w shared/api/{zasób}/changes/V{X}_{Y}_{Nazwa}.ts. Funkcja transformResponse() powinna konwertować dane z nowego formatu na stary — ta transformacja idzie wstecz, ponieważ klient na starszej wersji oczekuje starego formatu.
4. Jeśli obsługujesz żądania od starszych klientów, utwórz plik transformacji żądania w shared/api/{zasób}/requestChanges/V{X}_{Y}_{Nazwa}.ts. Funkcja transformRequest() konwertuje dane ze starego formatu na nowy — ta transformacja idzie do przodu, bo handler API oczekuje najnowszego formatu.
5. Zarejestruj wszystkie pliki zmian w shared/api/versionUtils/versionChangeRegistry.ts, aby skill mógł automatycznie stosować transformacje w prawidłowej kolejności.
6. Testuj przepływ: wyślij żądanie w starym formacie, sprawdź czy transformacja do nowego działa, a następnie sprawdź czy odpowiedź w nowym formacie jest poprawnie transformowana z powrotem do starego formatu dla klienta.