Wersjonowanie API w Workiva
Wersjonowanie interfejsu programowania aplikacji (API) to krytyczna praktyka przypisywania unikalnych identyfikatorów do różnych iteracji projektu API w celu skutecznego zarządzania zmianami i komunikowania ich. Jego głównym celem jest zachowanie kompatybilności wstecznej, zapewniając, że skrypty i aplikacje polegające na starszej wersji nie ulegną uszkodzeniu po wydaniu nowej wersji API. Ta stabilność pozwala dostawcom API na wprowadzanie głównych aktualizacji, poprawek błędów i nowych funkcji bez zakłócania pracy obecnych użytkowników, dając konsumentom czas i kontrolę potrzebną do migracji ich systemów, gdy będą na to gotowi. Ostatecznie, odpowiednie wersjonowanie API promuje niezawodny, skalowalny i profesjonalny ekosystem rozwoju.
2026-01-01 Wersja interfejsu API
W styczniu 2026 roku Workiva wyda nową wersję API, 2026-01-01. Nowa wersja wprowadza znaczące ulepszenia w wielu obszarach, w tym poprawioną spójność, nowe funkcje i wycofanie starszych funkcji. Korzyści z aktualizacji do wersji 2026-01-01 obejmują stałą kompatybilność z najnowszymi funkcjami platformy Workiva, zwiększone bezpieczeństwo, lepszą wydajność i możliwość wykorzystania nowych funkcji.
Aby uzyskać dodatkowe informacje na temat nowej wersji interfejsu API, zapoznaj się z Przewodnikiem aktualizacji interfejsu API Workiva 2026-01-01 .
Wycofanie wersji interfejsu API 2022-01-01
Wraz z wydaniem wersji 2026-01-01, starsza wersja 2022-01-01 wejdzie w fazę przestarzałą. Wsparcie dla tej starszej wersji będzie kontynuowane do jej wygaśnięcia w styczniu 2029 r., a wsparcie dla punktów końcowych 2022-01-01 Prototype zakończy się w styczniu 2027 r.
Uwaga: Większość prototypowych punktów końcowych w wersji 2022-01-01 została awansowana do ogólnej dostępności (GA) w wersji 2026-01-01.
| Wersja | Status | Typ punktu końcowego | Data zachodu słońca |
|---|---|---|---|
| 2026-01-01 | Ogólna dostępność (GA) | Wszystko | Nie dotyczy (bieżące) |
| 2022-01-01 | Przestarzałe | Prototyp | Styczeń 2027 r |
| 2022-01-01 | Przestarzałe | GA | Styczeń 2029 r |
Porównywanie wersji API
Po wydaniu nowej wersji, dokumentacja API dla tej wersji na Workiva Developers Hub zawiera sekcję Changelog, która zawiera szczegółową dokumentację zmian API w tej wersji. Wersja 2026-01-01 będzie miała sekcję 2026-01-01 Upgrade Guide z pełnym opisem zmian w tej wersji.
Ponadto dostępnych jest wiele narzędzi open source, które umożliwiają porównanie dwóch różnych wersji API. Tego typu narzędzia pozwalają na szybkie i szczegółowe porównywanie zmian wersji. Narzędzie open source oasdiff ma web-based Diff Calculator, który pozwala na przesłanie dwóch plików konfiguracyjnych wersji API (oas.yaml) i uruchomienie porównania dla łamania zmian, dzienników zmian lub surowej różnicy. Może wyświetlać wyniki w formacie tekstowym, yaml, json, html i markdown.
Odwołanie do określonej wersji API
Interfejsy API Workiva wykorzystują nagłówek X-Version, aby określić, która wersja API ma być używana. Jeśli nagłówek X-Version nie zostanie przekazany, wersja zostanie domyślnie ustawiona na przestarzałą wersję 2022-01-01.
Uwaga: Po styczniu 2029 r. nagłówek X-Version będzie wymagany, a wszystkie wywołania API bez niego zakończą się niepowodzeniem.
Aby określić wersję w żądaniu API za pośrednictwem Pythona, dołącz parę klucz/wartość w nagłówkach każdego żądania API. Na przykład: headers = {'X-Version': '2026-01-01'}
Obecnie możesz podać adres 2026-01-01 lub 2022-01-01.
Ponieważ w wersji 2026-01-01 wprowadzono wiele przełomowych zmian, krytyczne jest upewnienie się, że zarówno nagłówek X-Version jest ustawiony dla odpowiedniej wersji, jak i że ścieżka URL punktu końcowego API i parametry są zgodne z wymaganą strukturą tej wersji. Ponadto ważne jest, aby zrozumieć format odpowiedzi na wywołanie API i wszelkie potencjalne różnice w tym formacie między wersjami.
Przykłady
Przykład żądania GET
Oto przykład użycia żądania GET w punkcie końcowym Retrieve a List of Spreadsheets zarówno dla wersji 2026-01-01, jak i 2022-01-01 (te przykłady zawierają token na okaziciela jako zmienną tokena do celów zaciemniania w tym artykule).
wersja 2026-01-01
# 2026-01-01 version # zwróć uwagę na nagłówek X-Version i adres URL żądania headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2026-01-01', } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )wersja 2022-01-01
# wersja 2022-01-01 # zwróć uwagę na nagłówek X-Version i adres URL żądania headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, ) Przykład żądania PATCH
Poniżej znajduje się przykład użycia żądania PATCH w punkcie końcowym Partially Update a Single Section zarówno dla wersji 2026-01-01, jak i 2022-01-01 (te przykłady zawierają token na okaziciela jako zmienną tokena w tym artykule w celu zaciemnienia).
wersja 2026-01-01
# 2026-01-01 version # zwróć uwagę na nagłówek X-Version i adres URL żądania headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization':token, 'X-Version': '2026-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "My New Section Name" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) wersja 2022-01-01
# 2022-01-01 version # zwróć uwagę na nagłówek X-Version i adres URL żądania headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "My New Section Name" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) Wskazówka: Oprócz upewnienia się, że ścieżka URL i struktura parametrów są zgodne z odpowiednią wersją API, sprawdź dokumentację, aby uzyskać szczegółowe informacje na temat dostępnych opcji parametrów.
Na przykład w powyższym przykładzie częściowej aktualizacji pojedynczej sekcji, w wersji 2022-01-01 dostępne są trzy opcje ścieżek ( /name , /index , /parent ), ale w wersji 2026-01-01 dostępnych jest ponad trzydzieści opcji ścieżek.
Najlepsze praktyki dotyczące skryptów i wersjonowania API
Chociaż konkretna wersja API, której potrzebujesz, może zależeć od stanu aktywnych skryptów i aplikacji, harmonogramów aktualizacji do nowej wersji API lub innych czynników, poniżej przedstawiono kilka najlepszych praktyk związanych ze skryptami i wersjonowaniem API.
Zawsze podawaj wersję API
Nigdy nie polegaj na domyślnej wersji dostawcy API. Wyraźnie określ wersję w każdym wywołaniu API. Poprzez wyraźne określenie wersji masz kontrolę nad tym, która wersja skryptu lub aplikacji jest uruchamiana.
Scentralizuj stałą wersję
Zdefiniuj wersję API jako pojedynczą, łatwą do zlokalizowania stałą lub zmienną konfiguracyjną w górnej części skryptu lub w osobnym pliku konfiguracyjnym. Niezawodnie usprawnia to rozwiązywanie problemów i poprawia łatwość konserwacji. Przykład:
# config.py lub na górze głównego skryptu API_VERSION = '2026-01-01' # w wywołaniu requests headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, ) Unikaj mieszania wersji API
Nie próbuj mieszać wersji API w ramach jednego skryptu lub aplikacji. Wszystkie wywołania API w ramach jednego skryptu lub aplikacji powinny odwoływać się do tej samej wersji Workiva API (np. wszystkie wywołania API powinny używać wersji "2026-01-01"). Mieszanie wersji komplikuje debugowanie, schematy żądań i formaty odpowiedzi, sprawiając, że zachowanie skryptu jest nieprzewidywalne, a konserwacja bardziej skomplikowana.
Odizoluj logikę interakcji API
Utwórz dedykowany moduł lub zestaw funkcji (często nazywany "wrapperem" lub "klientem"), który obsługuje całą komunikację z zewnętrznym API. Ten wzorzec oddziela "logikę biznesową" twojego skryptu od "logiki komunikacji API" Jeśli interfejs API ulegnie zmianie (np. zmieni się adres URL punktu końcowego lub struktura żądania/odpowiedzi w nowej wersji interfejsu API), należy zaktualizować tylko funkcje opakowujące, a nie cały skrypt(y).
Łaskawa obsługa przestarzałych punktów końcowych i parametrów
Podczas migracji ze starej wersji API do nowej, spodziewaj się, że punkty końcowe i parametry mogą zostać zmienione lub usunięte. Upewnij się, że skrypt zawiera solidną obsługę błędów i rejestrowanie, ponieważ wspiera to najlepsze praktyki tworzenia skryptów, a także zwiększa prawdopodobieństwo, że błędy związane z wersją zostaną wychwycone i zarejestrowane.
Aby uzyskać dodatkowe informacje na temat najlepszych praktyk tworzenia skryptów, zapoznaj się z artykułem Workiva Scripting: Najlepsze praktyki programistyczne .
Monitoruj i planuj utratę wartości
Workiva przechodzi na dwa okna wydawnicze rocznie dla nowych głównych wersji: wiosenne i jesienne. W przypadku, gdy nie ma żadnych przełomowych zmian, gdy zbliża się data wydania, a kandydat do wydania dla tego okresu jest pusty, Workiva nie opublikuje nowej wersji API w tym czasie.
Zalecamy aktywne śledzenie strony internetowej Workiva API Developer Hub, subskrybowanie Workiva Release Notes oraz przestrzeganie opublikowanych harmonogramów wydań i wycofywania. Skrypty korzystające z przestarzałej wersji API zostaną ostatecznie uszkodzone. Znajomość daty wygaśnięcia (końca życia) wersji API pozwala zaplanować niezbędne prace aktualizacyjne przed datą wygaśnięcia.
Migracja i walidacja skryptów
Aby zapewnić płynną migrację wersji API, ustal strategię testowania równoległego: skopiuj istniejący skrypt produkcyjny, zmodyfikuj tylko kopię, aby była ukierunkowana na nową wersję API (w tym wszelkie wymagane zmiany nagłówków, ścieżki URL i / lub struktury żądań / odpowiedzi), a następnie przetestuj zarówno stare, jak i nowe skrypty, aby porównać i zweryfikować funkcjonalność i dane wyjściowe.
Uruchamiając je obok siebie w kontrolowanym środowisku, możesz użyć stabilnego starszego skryptu jako standardu do monitorowania i weryfikacji, czy funkcjonalność i wyniki generowane przez nowy skrypt są identyczne przed pełnym przejściem na nową wersję i wycofaniem starej wersji.