Strategieën voor API-versioning
Pas versioning toe via URL, header en querystring.
Strategieën voor API-versioning is een gratis C# Academy-les op CoddyKit. Dit is les 1 van 4. Je kunt de volledige les hieronder gratis lezen en daarna in de browser praktisch oefenen met een ingebouwde code-editor en een AI-begeleider die 24/7 beschikbaar is. Deze les maakt deel uit van het leertraject C# Academy. Je voortgang wordt gesynchroniseerd op het web en in de CoddyKit-app. De cursus C# Academy bevat in totaal 4 lessen.
Waarom een API versiebeheer geven
Zodra clients afhankelijk zijn van je API, mag je het contract niet breken. Met versiebeheer kun je wijzigingen die niet compatibel zijn in een nieuwe versie uitbrengen, terwijl oude clients met de oude versie blijven werken.
// v1 returns { name }
// v2 returns { firstName, lastName } (breaking)Versiebeheer via URL-pad
Bij de meest zichtbare strategie staat de versie in het pad. Dit is ondubbelzinnig en eenvoudig te routeren, te bekijken en te cachen.
GET /api/v1/products
GET /api/v2/productsVersiebeheer via querystring
De versie wordt meegestuurd als queryparameter. URL's blijven stabiel en een ontbrekende parameter kan standaard naar de nieuwste of een vaste versie verwijzen.
GET /api/products?api-version=1.0
GET /api/products?api-version=2.0Versiebeheer via header
Een aangepaste aanvraagheader bevat de versie, zodat de URL netjes blijft. Het nadeel is dat deze versie onzichtbaar is in de adresbalk van de browser en moeilijker handmatig te testen is.
GET /api/products
X-Api-Version: 2.0Versiebeheer via mediatype
Dit wordt ook inhoudsonderhandeling genoemd. De versie is opgenomen in het mediatype van de Accept-header. Dit is de meest REST-conforme, maar minst vindbare optie.
GET /api/products
Accept: application/json;v=2.0De strategieën vergelijken
Elke strategie ruilt vindbaarheid in tegen nette URL's:
- URL-pad: het best vindbaar, maar maakt URL's rommelig.
- Querystring: stabiele URL's en eenvoudige standaardwaarden.
- Header: nette URL's, maar verborgen voor browsers.
- Mediatype: de zuiverste REST-vorm, maar het lastigst in gebruik.
// Many teams pick URL path for public APIsSemantisch versiebeheer van API's
API-versies zijn meestal alleen hoofdversies (v1, v2). Gebruik kleine versienummers voor toevoegingen zonder brekende wijzigingen die oude clients kunnen negeren.
// v1.0 -> v1.1 : additive (safe)
// v1 -> v2 : breaking (new version)Uitfaseren
Verwijder een oude versie nooit abrupt. Markeer deze als verouderd, kondig een datum aan waarop de ondersteuning stopt en geef dit via headers door aan clients.
// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: trueStandaardversie
Bepaal wat er gebeurt wanneer een client geen versie meestuurt. Veelgebruikte keuzes zijn: de nieuwste versie aannemen, v1 aannemen of het verzoek weigeren. Expliciete keuzes voorkomen verrassingen.
// Strategy: unversioned request -> treat as v1.0De juiste onderdelen van versiebeheer voorzien
Voorzie het contract van versies (routes, aanvraag- en antwoordstructuren), niet de interne implementatiedetails. Een v2-eindpunt kan het grootste deel van de bedrijfslogica delen met v1.
// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2ControllerStrategieën combineren
De versiebeheerbibliotheek van ASP.NET Core kan de versie tegelijk uit verschillende bronnen lezen, zodat clients de handigste optie kunnen kiezen. Je configureert dit hierna.
// Accept version from URL OR header OR querySnelle controle
Toets of je de strategieën voor versiebeheer begrijpt.
Samenvatting
Je hebt strategieën voor API-versiebeheer verkend:
- URL-pad, querystring, header en mediatype.
- Elke strategie ruilt vindbaarheid in tegen nette URL's.
- Voorzie het contract van versies, faseer verouderde versies zorgvuldig uit en definieer een standaardversie.
Volgende: Asp.Versioning configureren in ASP.NET Core.
Leer C# met een AI-tutor — gratis
Schrijf echte code en voer die uit in je browser, krijg direct hulp van een AI-tutor die 24/7 beschikbaar is en ga verder waar je gebleven bent op het web of in de app.
- Cursussen
- 93
- Lessen
- 346
Veelgestelde vragen
Is de les “Strategieën voor API-versioning” gratis?
Ja — de volledige tekst van “Strategieën voor API-versioning” kun je hier gratis op het web lezen. Als je interactief wilt oefenen met een ingebouwde code-editor en een AI-begeleider die 24/7 beschikbaar is, en de rest van de cursus C# Academy wilt ontgrendelen, kun je upgraden naar CoddyKit PRO. De cursus C# Academy bevat in totaal 4 lessen.
Wat leer ik in “Strategieën voor API-versioning”?
Pas versioning toe via URL, header en querystring. Je oefent met C# Academy door code rechtstreeks in de browser uit te voeren. Een AI-begeleider die 24/7 beschikbaar is beantwoordt je vragen terwijl je de les doorwerkt.
Heb ik ervaring nodig om met C# Academy te beginnen?
Ervaring vooraf is niet nodig. C# Academy op CoddyKit is opgebouwd voor beginners tot gevorderden, zodat je hier of bij het begin kunt starten en in je eigen tempo kunt leren. Dit is les 1 van 4.
Hoe lang duurt de les “Strategieën voor API-versioning”?
De meeste lessen van CoddyKit duren ongeveer 5–10 minuten. Elke les is kort en interactief, zodat je gestaag vooruitgaat en op het web en in de app precies verdergaat waar je was gebleven.
Kan ik code schrijven en uitvoeren in deze les over C# Academy?
Ja. Elke les over C# Academy bevat een ingebouwde code-editor, zodat je rechtstreeks in je browser echte code kunt schrijven en uitvoeren en direct feedback van AI krijgt — lokale installatie is niet nodig.
Alle lessen in deze cursus
- Strategieën voor API-versioning
- Asp.Versioning configureren
- OpenAPI-documenten genereren
- API's met versies documenteren