Przejdź do głównej zawartości
DUST Docs

Zgodność i wersjonowanie

DUST API jest wersjonowane w ścieżce — każdy punkt końcowy znajduje się pod /api/v1. W ramach wersji stale rozwijamy API, ale według ścisłych zasad: zmiany są domyślnie addytywne, wszystko, co mogłoby zepsuć poprawnie napisaną integrację, najpierw przechodzi przez okres wycofywania, a opublikowana specyfikacja OpenAPI jest w każdej chwili wiążącym opisem kontraktu.

Na tej stronie opisano, co oznacza „poprawnie napisana” integracja i co obiecujemy w zamian.

Co może się zmienić bez powiadomienia

Dział zatytułowany „Co może się zmienić bez powiadomienia”

Poniższe zmiany są uznawane za zgodne wstecznie. Mogą pojawić się w dowolnym wydaniu, a twoja integracja musi je tolerować:

  • Nowe punkty końcowe i nowe operacje w istniejących ścieżkach.
  • Nowe opcjonalne parametry żądań, nagłówki i pola treści. Istniejące żądania nadal działają bez zmian.
  • Nowe pola w odpowiedziach. Obiekty z czasem się rozrastają.
  • Nowe wartości w polach wyliczeniowych — w miarę rozwoju produktu dodawane są nowe typy zdarzeń, stany i rodzaje.
  • Nowe kody błędów dla przypadków niepowodzenia, które wcześniej zgłaszano za pomocą ogólnego kodu.
  • Dokumentacja, tekst message błędów i kolejność pól. Ciągi czytelne dla człowieka nie są częścią kontraktu; kolejność składowych JSON nigdy nie ma znaczenia.

Tworzenie integracji, która pozostaje zgodna

Dział zatytułowany „Tworzenie integracji, która pozostaje zgodna”

Powyższe zasady są bezpieczne, jeśli klient stosuje standardową praktykę tolerancyjnego czytnika (tolerant reader):

  • Ignoruj nierozpoznane pola odpowiedzi. Nigdy nie zgłaszaj błędu z powodu nieoczekiwanych składowych i nie stosuj ścisłej walidacji schematu, która odrzuca nieznane pola.
  • Toleruj nieznane wartości wyliczeniowe. Rozgałęziaj logikę według obsługiwanych wartości, a nieobsługiwane przekazuj do bezpiecznej ścieżki domyślnej.
  • Rozgałęziaj logikę według code błędu, nigdy według message. Kody są stabilnymi identyfikatorami; komunikaty są lokalizowane i mogą zmieniać brzmienie. Zobacz Konwencje żądań.
  • Traktuj ID i kursory paginacji jako nieprzezroczyste ciągi znaków. Zapisuj je i odtwarzaj; nigdy ich nie analizuj ani nie konstruuj.
  • Wywołuj tylko to, co opisuje opublikowana specyfikacja. Punkty końcowe, pola i zachowania nieujęte w publicznej specyfikacji OpenAPI nie są objęte żadną obietnicą zgodności.

Integracja przestrzegająca tych zasad nie jest dotknięta zmianami addytywnymi i to właśnie ją chronią poniższe obietnice.

Co uznajemy za zmianę niezgodną

Dział zatytułowany „Co uznajemy za zmianę niezgodną”

Nie wykonujemy żadnej z poniższych zmian w opublikowanej operacji /api/v1 bez opisanego niżej procesu wycofywania:

  • Usunięcie lub zmiana nazwy punktu końcowego, parametru żądania lub pola odpowiedzi.
  • Zmiana typu lub formatu pola.
  • Przekształcenie opcjonalnych danych wejściowych żądania w wymagane lub zawężenie wartości akceptowanych przez dane wejściowe.
  • Usunięcie wartości z pola wyliczeniowego.
  • Zmiana code błędu lub statusu HTTP zwracanego dla istniejącego, udokumentowanego przypadku niepowodzenia.
  • Wymaganie wyższego poziomu autoryzacji lub nowego uprawnienia dla istniejącej operacji.
  • Istotna zmiana semantyki operacji, nawet jeśli jej struktura pozostaje niezmieniona.

Wycofywanie

Dział zatytułowany „Wycofywanie”

Gdy musimy wycofać lub przebudować jakiś element, najpierw oznaczamy go jako przestarzały:

  • Operacja lub pole zostaje oznaczone jako deprecated: true w opublikowanej specyfikacji OpenAPI, a informacja o wycofaniu pojawia się w tej dokumentacji.
  • Przestarzała funkcjonalność nadal działa bez zmian przez co najmniej 90 dni od ogłoszenia.
  • Udokumentowany zamiennik jest dostępny przed ogłoszeniem wycofania lub w chwili ogłoszenia, o ile taki zamiennik istnieje.

Wersjonowanie

Dział zatytułowany „Wersjonowanie”

Nowe wersje główne z założenia pojawiają się rzadko. /api/v1 rozwija się addytywnie; /api/v2 wprowadzilibyśmy tylko w przypadku przebudowy, której nie da się wyrazić w sposób zgodny, a /api/v1 byłoby wówczas nadal obsługiwane przez długi, wyraźnie ogłoszony okres migracji — nigdy nie zostałoby usunięte w ramach opisanego wyżej okresu wycofywania.

Zobacz też

Dział zatytułowany „Zobacz też”
Pomoc techniczna i zgłoszeniaZgłoś problem z dokumentacją