api-versioning

Skill do tworzenia i utrzymania zmian w wersjach API. Automatycznie transformuje dane między wersjami — nowe żądania konwertuje do najnowszego formatu, a odpowiedzi wysyła w formacie oczekiwanym przez klienta. Obsługuje zmiany łamiące kompatybilność wstecz poprzez pojedyncze kroki mapowania między kolejnymi wersjami. Idealny do zarządzania ewolucją API bez przerywania usługi dla starszych klientów.

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.