C# Academy · Lekcja

Strategie wersjonowania API

Wersjonuj API za pomocą adresu URL, nagłówka i parametrów zapytania.

Strategie wersjonowania API to bezpłatna lekcja C# Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej C# Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs C# Academy zawiera 4 lekcji w sumie.

Dlaczego wersjonować API

Gdy klienci zaczną polegać na Państwa API, nie można złamać jego kontraktu. Wersjonowanie pozwala wprowadzać zmiany powodujące niezgodność w nowej wersji, podczas gdy starsi klienci nadal korzystają ze starej.

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

Wersjonowanie w ścieżce URL

Najbardziej widoczna strategia umieszcza wersję w ścieżce. Jest jednoznaczna i ułatwia wyznaczanie tras, przeglądanie oraz buforowanie.

GET /api/v1/products
GET /api/v2/products

Wersjonowanie za pomocą parametrów zapytania

Wersja jest przekazywana jako parametr zapytania. Adresy URL pozostają stabilne, a brak parametru może oznaczać wersję najnowszą lub ustaloną z góry.

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

Wersjonowanie za pomocą nagłówka

Niestandardowy nagłówek żądania przenosi informację o wersji, dzięki czemu adres URL pozostaje przejrzysty. Wadą jest to, że wersja nie jest widoczna w pasku adresu przeglądarki i trudniej testować ją ręcznie.

GET /api/products
X-Api-Version: 2.0

Wersjonowanie za pomocą typu mediów

Nazywane również negocjacją treści. Wersja jest osadzona w typie mediów nagłówka Accept. To najbardziej zgodna z REST, ale najmniej intuicyjna do wykrycia opcja.

GET /api/products
Accept: application/json;v=2.0

Porównanie strategii

Każda strategia stanowi kompromis między łatwością wykrycia wersji a przejrzystością adresu URL:

Ścieżka URL: najwyższa łatwość wykrycia, ale zaśmiecone adresy URL.
Parametr zapytania: stabilne adresy URL i łatwe wartości domyślne.
Nagłówek: przejrzyste adresy URL, ale wersja ukryta przed przeglądarkami.
Typ mediów: najczystsza forma REST, ale najtrudniejsza w użyciu.

// Many teams pick URL path for public APIs

Wersjonowanie semantyczne API

Wersje API zwykle ogranicza się do numerów głównych (v1, v2). Wersje pomniejsze należy rezerwować dla dodatkowych, niepowodujących niezgodności zmian, które starsi klienci mogą zignorować.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

Wycofywanie

Nigdy nie należy nagle usuwać starej wersji. Należy oznaczyć ją jako przestarzałą, ogłosić datę wycofania i poinformować o tym klientów za pomocą nagłówków.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

Wersja domyślna

Należy ustalić, co się stanie, gdy klient nie prześle wersji. Typowe możliwości to: przyjęcie najnowszej wersji, przyjęcie v1 albo odrzucenie żądania. Jednoznaczne określenie tego zachowania pozwala uniknąć niespodzianek.

// Strategy: unversioned request -> treat as v1.0

Wersjonowanie właściwych elementów

Należy wersjonować kontrakt (trasy oraz kształty żądań i odpowiedzi), a nie wewnętrzne szczegóły implementacji. Endpoint v2 może współdzielić większość logiki biznesowej z v1.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

Łączenie strategii

Biblioteka do wersjonowania w ASP.NET Core może jednocześnie odczytywać wersję z kilku źródeł, pozwalając klientom wybrać najwygodniejsze z nich. Konfiguracja nastąpi w dalszej części.

// Accept version from URL OR header OR query

Szybki test

Sprawdź swoje rozumienie strategii wersjonowania.

Podsumowanie

Omówili Państwo strategie wersjonowania API:

ścieżka URL, parametr zapytania, nagłówek oraz typ mediów.
Każda z nich stanowi kompromis między łatwością wykrycia wersji a przejrzystością adresu URL.
Należy wersjonować kontrakt, łagodnie wycofywać starsze wersje i zdefiniować wersję domyślną.

Następnie: konfigurowanie Asp.Versioning w ASP.NET Core.

Często zadawane pytania

Czy lekcja „Strategie wersjonowania API” jest bezpłatna?

Tak — pełny tekst „Strategie wersjonowania API” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu C# Academy, przejdź na CoddyKit PRO. Kurs C# Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Strategie wersjonowania API”?

Wersjonuj API za pomocą adresu URL, nagłówka i parametrów zapytania. Ćwiczysz C# Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć C# Academy?

Nie wymagamy żadnego doświadczenia. C# Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.

Ile czasu zajmuje lekcja „Strategie wersjonowania API”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji C# Academy?

Tak. Każda lekcja C# Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do C# Academy