Wersjonowanie API i zgodność wsteczna
Poznaj strategie rozwijania API bez przerywania działania istniejących klientów, w tym schematy wersjonowania i zasady zgodności.
Wersjonowanie API i zgodność wsteczna to bezpłatna lekcja System Design Basics for Backend Developers na CoddyKit. To lekcja 4 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 System Design Basics for Backend Developers, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs System Design Basics for Backend Developers zawiera 4 lekcji w sumie.
Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.
Why APIs Must Evolve Carefully
Once an API has clients, you cannot freely change it. Renaming a field or removing an endpoint can break every consumer. Versioning lets you evolve the API while existing clients keep working.
Breaking vs Non-Breaking Changes
Know the difference:
- Non-breaking: adding a new optional field, adding a new endpoint
- Breaking: removing a field, renaming a field, changing a type, making an optional field required
Non-breaking changes can ship without a new version; breaking ones cannot.
URI Versioning
The most visible scheme puts the version in the path. It is simple and cache-friendly, and clients can clearly see which version they call.
GET /v1/users/42
GET /v2/users/42Header Versioning
Alternatively, clients request a version via a header. This keeps URIs clean and treats the version as part of content negotiation.
GET /users/42
Accept: application/vnd.myapp.v2+jsonQuery Parameter Versioning
A lighter approach uses a query parameter, e.g. ?version=2. It is easy to test in a browser but mixes versioning with regular parameters and can complicate caching.
GET /users/42?version=2Semantic Versioning
SemVer (MAJOR.MINOR.PATCH) communicates intent:
- MAJOR: breaking changes
- MINOR: new backward-compatible features
- PATCH: backward-compatible fixes
For public HTTP APIs, the MAJOR number usually maps to the URI version.
Additive Change Discipline
The cheapest versioning is not needing a new version. Follow the additive rule: only add, never remove or rename. Clients ignore unknown fields, so adding is safe.
{
"id": 42,
"name": "Ada",
"email": "ada@x.com"
}
// Later, safely add:
{
"id": 42,
"name": "Ada",
"email": "ada@x.com",
"created_at": "2026-01-01"
}Deprecation, Not Deletion
When you must retire something, deprecate first. Mark it in docs, send a Deprecation or Sunset header, and give clients a clear timeline before removal.
HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: </v2/users>; rel="successor-version"Versioning gRPC and GraphQL
It is not just REST. In gRPC, never reuse or renumber protobuf field tags — that breaks the wire format. In GraphQL, the convention is no versions at all: add fields and use the @deprecated directive on old ones.
Supporting Multiple Versions
Running several versions at once has a cost. Strategies include translating old requests to the new internal model, or routing versions to different handlers. Limit how many versions you support and sunset old ones on schedule.
Designing for Change Up Front
Reduce future pain by designing for evolution: prefer objects over bare values so you can add fields, avoid leaking internal enums, and document a clear compatibility contract from day one.
Quick Check
Test your understanding of API versioning.
Recap
You learned how to evolve APIs safely:
- Distinguish breaking from non-breaking changes
- URI, header, and query parameter versioning schemes
- SemVer and the additive-change discipline
- Deprecate with Sunset headers before deleting
- gRPC tag stability and GraphQL's deprecation approach
Często zadawane pytania
Czy lekcja „Wersjonowanie API i zgodność wsteczna” jest bezpłatna?
Tak — pełny tekst „Wersjonowanie API i zgodność wsteczna” 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 System Design Basics for Backend Developers, przejdź na CoddyKit PRO. Kurs System Design Basics for Backend Developers zawiera 4 lekcji w sumie.
Co nauczysz się w „Wersjonowanie API i zgodność wsteczna”?
Poznaj strategie rozwijania API bez przerywania działania istniejących klientów, w tym schematy wersjonowania i zasady zgodności. Ćwiczysz System Design Basics for Backend Developers 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ąć System Design Basics for Backend Developers?
Nie wymagamy żadnego doświadczenia. System Design Basics for Backend Developers 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 4 z 4.
Ile czasu zajmuje lekcja „Wersjonowanie API i zgodność wsteczna”?
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 System Design Basics for Backend Developers?
Tak. Każda lekcja System Design Basics for Backend Developers 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
- Zasady projektowania interfejsów RESTful API
- GraphQL i gRPC
- Kolejki komunikatów i architektury sterowane zdarzeniami
- Wersjonowanie API i zgodność wsteczna