Wersjonowanie

Wersja Partner API jest określona w adresie URL. Bieżąca wersja to:

https://partner-api.performancehub.co/partner/v1/

Zasady wprowadzania zmian

Performance Hub dąży do tego, aby w miarę możliwości wprowadzać zmiany addytywne i zgodne wstecz.

Przykłady zmian zgodnych wstecz:

• Dodanie nowego opcjonalnego pola do żądania.
• Dodanie nowego pola do odpowiedzi.
• Dodanie nowego punktu końcowego.
• Dodanie nowej wartości wyliczeniowej, gdy oczekuje się, że klienci obsługują nieznane wartości.
• Ulepszenie komunikatów walidacji bez zmiany kontraktu kodów stanu.

access_time_windows i access_time_windows_revision to addytywne pola żądania dotyczącego członka. Istniejący klienci, którzy je pomijają, zachowują zapisaną migawkę Access Time Windows bez zmian. Ta reguła pomijania zapewnia zgodność z częściowymi operacjami upsert; pominięcie nie jest równoznaczne z wysłaniem pustej tablicy.

Przykłady zmian powodujących niezgodność:

• Usunięcie pola lub zmiana jego nazwy.
• Zmiana typu pola.
• Zmiana opcjonalnego pola żądania na wymagane.
• Usunięcie punktu końcowego.
• Zmiana znaczenia istniejącego kodu stanu lub specyficznego dla domeny pola reason.

Wycofywanie

Gdy konieczna jest zmiana powodująca niezgodność, Performance Hub w miarę możliwości nie będzie zmieniać istniejącej wersji. Zamiast tego wprowadzimy nową wersję lub ścieżkę migracji i poinformujemy o zmianie partnerów, których ona dotyczy.

Powiadomienia o wycofaniu mogą obejmować:

• Wpis w dzienniku zmian.
• Bezpośrednią komunikację z partnerem.
• Uwagi w Partner Console.
• Wskazówki dotyczące migracji w dokumentacji.

Zalecenia dla klientów

Twórz klientów odpornych na zmiany addytywne:

• Ignoruj pola odpowiedzi, z których nie korzystasz.
• Traktuj nieznane wartości wyliczeniowe jako nieobsługiwane, zamiast doprowadzać do awarii.
• Unikaj ścisłego porównywania odpowiedzi.
• Rejestruj nierozpoznane wartości, aby świadomie aktualizować integrację.

W przypadku wersjonowanych części danych członka, takich jak Access Time Windows, przechowuj przesłaną wersję i znormalizowany ładunek do czasu poznania wyniku. Ponowne użycie wersji dla zmienionej zawartości powoduje konflikt, a ponowne odtworzenie tej samej zawartości jest idempotentne. Zobacz Access Time Windows.

Specyfikacje OpenAPI

Korzystaj z opublikowanych specyfikacji OpenAPI do generowania klientów, walidacji żądań i śledzenia zmian struktury API w czasie.

Zobacz Specyfikacje OpenAPI.