API versioning/pl

Ta strona opisuje zasady kontroli wersji API (Application programming interface tj. interfejs aplikacji do programowania) dla Wikimedia REST APIs,które są opisane w /api/rest_v1/?doc dla każdej wiki.

Globalna wersja interfejsu API
Globalna wersja interfejsu API jest częścią ścieżki. Przykład:. Zgodnie z zasadami semantic versioning, jest on zwiększany, gdy stabilny punkt końcowy jest zmieniany w sposób niekompatybilny wstecz. W przypadku wersji globalnej rozważamy przerwanie zmian, jeśli zostaną usunięte stabilne punkty końcowe, lub struktura żądań zmienia się w sposób niezgodny. Typy treści są wersjonowane za pomocą negocjacji treści i nie wyzwalają przyrostów wersji globalnej. Ponieważ wprowadzenie nowej dużej wersji interfejsu API jest bardzo uciążliwym wydarzeniem, staramy się unikać łamania stabilnych punktów końcowych.

Stabilność punktu końcowego
Każdy punkt końcowy interfejsu API jest oznaczony klasą stabilności: Stabilny, Niestabilny, eksperymentalny lub przestarzałe. Zazwyczaj, Punkty końcowe interfejsu API rozpoczynają się jako eksperymentalne lub niestabilne, a z czasem stają się częścią stabilnego interfejsu API.

Stabilny
Stabilne punkty końcowe gwarantują, że nie zmienią się w niekompatybilny sposób. Oznacza to, że możesz być pewien, że podstawowy interfejs, udokumentowany przez specyfikację, będzie działał zgodnie z opisem.

Niestabilny
Punkty końcowe oznaczone jako niestabilne mogą się zmieniać w sposób niekompatybilny bez zwiększania wartości poważny Wersja API, ale będą zwiększać mniejsze wersje. Zwrócimy się do użytkowników i wspólnie podejmujemy wysiłki, aby uniknąć zerwania z dotychczasowymi klientami.

Eksperymentalny
Eksperymentalne punkty końcowe mogą się zmieniać w niekompatybilny sposób w dowolnym czasie, bez zwiększania wersji interfejsu API. Zapraszamy do korzystania z nich na własne ryzyko.

Przestarzałe
Jeśli punkt końcowy jest oznaczony jako przestarzały, oznacza to, że nie był przydatny dla klientów i w konsekwencji zostanie usunięty w najbliższej przyszłości. Jeśli twój kod używa takiego punktu końcowego, powinieneś przestać go używać tak szybko, jak to możliwe. Zawsze zapewniamy użytkownikom alternatywne sposoby uzyskiwania tych samych informacji.

Stabilność formatu treści i -negocjacja
Zmiany w strukturze zwróconych treści będą wyraźnie wskazywane przez zmianę w części profilu typu MIME: text/html; charset=utf-8; profile=" https://www.mediawiki.org/wiki/Specs/HTML/1.2.1 " Aby uzyskać bardziej stabilny format wyjściowy, należy wysłać wiadomość  nagłówek z oczekiwanym typem MIME: Zaakceptuj: text/html; charset=utf-8; profile=" https://www.mediawiki.org/wiki/Specs/HTML/1.2.1 " W przypadku zmiany formatu wyjściowego interfejs API będzie nadal odpowiadał żądanym formatem, nawet jeśli dostępny jest nowszy format. Obsługa starych formatów wyjściowych będzie zwykle utrzymywana do momentu, gdy użycie spadnie poniżej niskiego progu. Formaty wycofane zostaną ogłoszone z wystarczającym ostrzeżeniem the API-announce list.

Tło: Jak interpretujemy semver w negocjacjach formatowych
Nasze adresy URL na ogół kończą się numerem wersji opartym na semver semantic versioning scheme. W wersjach semantycznych wszystkie niezgodne wstecz zmiany wywołują przyrost głównego numeru wersji (ex: 1.2.1 do 2.0.0). Ponieważ celem naszego mechanizmu negocjacji formatu jest unikanie łamania klientów, właśnie na tym się koncentrujemy. Klienci są zachęcani do podania dokładnej wersji, z którą testowali, ale API zazwyczaj zwróci wartość najnowszy typ zawartości zgodny z żądanym poważny wersja. Dokładniej, zwrócimy ostatnią wersję drugorzędną zgodną z wymaganą wersją główną, ale nie będziemy udzielać gwarancji co do zwróconej wersji poprawki ze względu na wydajność.

Zobacz także

 * Specs page hierarchy on this wiki dokumenty wersjonowane formaty treści./ documents versioned content formats.
 * Zobacz RFC discussion jak również this section of this article's talk page na tle tego, jak doszliśmy do przedstawionej tutaj strategii kontroli wersji.