API-versioning met Nginx
Configureer Nginx voor ondersteuning van verschillende API-versies, zodat upgrades soepel verlopen en achterwaartse compatibiliteit behouden blijft.
API-versioning met Nginx is een gratis API-gateway en reverse proxy (Nginx + Spring Cloud Gateway)-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 API-gateway en reverse proxy (Nginx + Spring Cloud Gateway). Je voortgang wordt gesynchroniseerd op het web en in de CoddyKit-app. De cursus API-gateway en reverse proxy (Nginx + Spring Cloud Gateway) bevat in totaal 4 lessen.
Wat is API-versioning?
Wanneer je API's bouwt, veranderen deze vaak in de loop van de tijd. Er worden nieuwe functies toegevoegd, oude functies verwijderd of de logica wordt bijgewerkt.
API-versioning is een strategie om deze veranderingen te beheren zonder bestaande applicaties die afhankelijk zijn van je API te breken.
Hierdoor kunnen verschillende versies van je API naast elkaar bestaan, zodat zowel oudere als nieuwere clients gelijktijdig worden ondersteund.
Waarom versioning belangrijk is
Stel je voor dat je je API bijwerkt en plotseling alle apps die de oude API gebruiken niet meer werken. Dat is geen prettige ervaring!
- Achterwaartse compatibiliteit: zorgt ervoor dat oudere clients blijven functioneren.
- Gecontroleerde upgrades: geeft clients de mogelijkheid om in hun eigen tempo naar nieuwe versies te migreren.
- Risicobeheer: isoleert wijzigingen en verkleint het risico op grootschalige problemen.
Veelgebruikte versioningbenaderingen
Er zijn verschillende manieren om een API-versie aan te geven:
- URL-pad:
/api/v1/users - Aangepaste header:
X-API-Version: 1 - Queryparameter:
/api/users?version=1
Bij Nginx is versioning via het URL-pad vaak het eenvoudigst en gebruikelijkst om te implementeren met location-blokken. Daar richten we ons op.
Nginx voor versioning op basis van URL's
Nginx gebruikt location-blokken om specifieke URL-patronen te herkennen. Dit is ideaal om aanvragen te routeren op basis van een versienummer in het pad.
Aanvragen naar /api/v1/ kunnen bijvoorbeeld naar één backend worden gestuurd, terwijl aanvragen naar /api/v2/ naar een andere backend gaan.
Zo kun je verschillende versies van je API-applicatie implementeren, waarbij elke versie haar eigen specifieke versie aanbiedt.
API-versie 1 instellen
We configureren Nginx om aanvragen voor /api/v1/ naar een backendserver te routeren waarop onze eerste API-versie draait.
We definiëren een upstream-blok voor onze backendservice en vervolgens een location-blok om aanvragen door te sturen.
http {
upstream api_v1_backend {
server 192.168.1.10:8080;
}
server {
listen 80;
server_name example.com;
location /api/v1/ {
proxy_pass http://api_v1_backend/;
proxy_set_header Host $host;
}
}
}API-versie 2 toevoegen
Nu introduceren we een nieuwe versie van onze API. We stellen een afzonderlijk upstream- en location-blok in voor /api/v2/ en routeren dit naar een andere backendserver.
Dit laat zien hoe Nginx verkeer naar volledig afzonderlijke implementaties van applicaties kan sturen op basis van de API-versie.
http {
upstream api_v1_backend {
server 192.168.1.10:8080;
}
upstream api_v2_backend {
server 192.168.1.11:8081;
}
server {
listen 80;
server_name example.com;
location /api/v1/ {
proxy_pass http://api_v1_backend/;
proxy_set_header Host $host;
}
location /api/v2/ {
proxy_pass http://api_v2_backend/;
proxy_set_header Host $host;
}
}
}De standaard- of basisversie afhandelen
Wat gebeurt er als een client geen versie opgeeft? Je kunt Nginx configureren om door te sturen naar de nieuwste versie of een standaardversie aan te bieden.
Met een rewrite-regel kun je de URI intern wijzigen zodat deze naar /api/v2/ verwijst wanneer de client /api/ zonder versie opvraagt.
http {
# ... upstream blocks ...
server {
listen 80;
server_name example.com;
# Redirect /api/ to /api/v2/ internally
location = /api/ {
rewrite ^ /api/v2/ permanent;
}
location /api/v1/ {
proxy_pass http://api_v1_backend/;
proxy_set_header Host $host;
}
location /api/v2/ {
proxy_pass http://api_v2_backend/;
proxy_set_header Host $host;
}
}
}Prefixmatching en afsluitende schuine strepen
Let goed op hoe location-blokken overeenkomsten vinden. Een location /api/v1 komt overeen met /api/v1, /api/v1/ en /api/v1something.
Het gebruik van location /api/v1/ (met een afsluitende schuine streep) is doorgaans veiliger: het komt overeen met /api/v1/ en de onderliggende paden, bijvoorbeeld /api/v1/users, maar niet met /api/v10.
De directive proxy_pass verwerkt afsluitende schuine strepen ook. Als proxy_pass http://backend/; een afsluitende schuine streep heeft, verwijdert Nginx het overeenkomende deel van de URI voordat het deze doorstuurt.
Best practices voor versioning
Volg deze richtlijnen om je API-versioning soepel en effectief te laten verlopen:
- Documenteer duidelijk: informeer clients over beschikbare versies en de planning voor het beëindigen van ondersteuning.
- Wees consistent: gebruik dezelfde versioningstrategie voor al je API's.
- Plan het beëindigen van ondersteuning: geef ruim van tevoren aan wanneer oude versies worden verwijderd.
- Monitor het gebruik: houd bij welke versies nog worden gebruikt om beslissingen over het beëindigen van ondersteuning te onderbouwen.
Nginx-versioningquiz
Bekijk de volgende Nginx-configuratie. Naar welke proxy_pass-bestemming wordt een aanvraag naar http://example.com/api/v1/products gerouteerd?
server {
listen 80;
server_name example.com;
location /api/v1/ {
proxy_pass http://backend_old_api/;
}
location /api/v2/ {
proxy_pass http://backend_new_api/;
}
location / {
proxy_pass http://default_backend/;
}
}Samenvatting: API-versioning met Nginx
Je hebt geleerd hoe je API-versioning met Nginx implementeert!
- Versioning helpt bij het beheren van API-wijzigingen en compatibiliteit met clients.
- De
location-blokken van Nginx zijn ideaal voor versioning op basis van URL's. - Je kunt verschillende API-versies naar afzonderlijke backendservices routeren.
- Met
rewrite-regels kun je standaardaanvragen of aanvragen zonder versienummer afhandelen.
Zo kun je je API's geleidelijk ontwikkelen en tegelijk dienstverlening aan al je gebruikers blijven bieden.
Leer API-gateway en reverse proxy (Nginx + Spring Cloud Gateway) 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
- 12
- Lessen
- 48
Veelgestelde vragen
Is de les “API-versioning met Nginx” gratis?
Ja — de volledige tekst van “API-versioning met Nginx” 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 API-gateway en reverse proxy (Nginx + Spring Cloud Gateway) wilt ontgrendelen, kun je upgraden naar CoddyKit PRO. De cursus API-gateway en reverse proxy (Nginx + Spring Cloud Gateway) bevat in totaal 4 lessen.
Wat leer ik in “API-versioning met Nginx”?
Configureer Nginx voor ondersteuning van verschillende API-versies, zodat upgrades soepel verlopen en achterwaartse compatibiliteit behouden blijft. Je oefent met API-gateway en reverse proxy (Nginx + Spring Cloud Gateway) 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 API-gateway en reverse proxy (Nginx + Spring Cloud Gateway) te beginnen?
Ervaring vooraf is niet nodig. API-gateway en reverse proxy (Nginx + Spring Cloud Gateway) 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 “API-versioning met Nginx”?
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 API-gateway en reverse proxy (Nginx + Spring Cloud Gateway)?
Ja. Elke les over API-gateway en reverse proxy (Nginx + Spring Cloud Gateway) 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
- API-versioning met Nginx
- Cross-Origin Resource Sharing (CORS)
- Rate limiting en throttling met Nginx
- Op paden gebaseerde routing naar microservices