Polityka wersjonowania API¶

Dotyczy publicznego REST (#46, ADR 0015). Wersja jest w ścieżce: /v1/...; każda odpowiedź /v1 ma nagłówek X-API-Version: v1.

Co jest stabilne w `/v1`¶

Ścieżki, metody, nazwy i typy pól wejścia/wyjścia, format błędów i kody z errors.md.

Nowy endpoint, nowe opcjonalne pole wejścia, nowe pole w odpowiedzi, nowy kod błędu, nowa reguła w katalogu, nowy profil. Klient musi ignorować nieznane pola odpowiedzi.
Zmiana treści message błędów i opisów w OpenAPI.

Usunięcie/zmiana nazwy pola lub endpointu, zmiana typu, nowe pole wymagane, zmiana znaczenia code, zmiana semantyki wyniku (np. skali score).
Wyjątek bety (#142): w zamkniętej becie identyfikatory zasobów zmieniły się z liczb na nieprzejrzyste publiczne id (rep_…, prj_…, zob. Identifiers) bez /v2.
Wersjonowanie reguł (ver) i promptu (PROMPT_VER) jest osobne: zmienia wyniki, nie kontrakt. Raport zawiera te wersje, więc klient widzi, czym go policzono.

Wycofywany endpoint/wersja dostaje nagłówki Deprecation (RFC 9745) i Sunset (RFC 8594) z datą wyłączenia oraz Link: <…>; rel="deprecation" do opisu migracji.
Okres wsparcia: minimum 6 miesięcy od ogłoszenia deprecjacji do Sunset; /vN i /vN+1 działają równolegle w tym czasie.
Ogłoszenie: CHANGELOG (sekcja API; osobny changelog docs/api/ — ADR 0015, planowany).