Wersjonowanie

Wersja główna jest częścią ścieżki: /api/v1.

#Co może się zmienić w v1 (bez zapowiedzi)

• nowe endpointy, zdarzenia i opcjonalne parametry żądań;
• nowe pola w odpowiedziach i treści zdarzeń;
• nowe wartości wyliczeń (statusy, typy zdarzeń, kody błędów);
• czytelniejsze komunikaty błędów (detail).

Twój klient musi ignorować nieznane pola i tolerować nieznane wartości wyliczeń. Nie waliduj odpowiedzi zamkniętym schematem.

#Zmiany niezgodne wstecz

Usunięcie lub zmiana nazwy pola, zmiana jego typu lub znaczenia albo uczynienie parametru wymaganym trafia do nowej wersji głównej (/api/v2). Po udostępnieniu v2 wersja v1 działa jeszcze co najmniej 12 miesięcy. W tym czasie:

• odpowiedzi wycofywanych operacji mają nagłówki Deprecation (RFC 9745) i Sunset (RFC 8594);
• administratorzy IT organizacji, które wciąż ich używają, dostają e-mail;
• lista zmian opisuje, co się zmieniło i jak przejść na nową wersję.

Dokument OpenAPI (https://api.elearning.edu.pl/openapi.json) stosuje wersjonowanie semantyczne w info.version.