Versionamento delle API e compatibilità retroattiva
Impari le strategie per far evolvere le API senza interrompere i client esistenti, inclusi gli schemi di versionamento e le regole di compatibilità.
Versionamento delle API e compatibilità retroattiva è una lezione System Design Basics for Backend Developers gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento System Design Basics for Backend Developers, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso System Design Basics for Backend Developers include 4 lezioni in totale.
Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.
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
Impara System Design Basics for Backend Developers con un tutor IA — gratis
Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.
- Corsi
- 12
- Lezioni
- 48
Domande Frequenti
La lezione «Versionamento delle API e compatibilità retroattiva» è gratuita?
Sì — il testo completo di «Versionamento delle API e compatibilità retroattiva» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso System Design Basics for Backend Developers, passa a CoddyKit PRO. Il corso System Design Basics for Backend Developers include 4 lezioni in totale.
Cosa imparerò in «Versionamento delle API e compatibilità retroattiva»?
Impari le strategie per far evolvere le API senza interrompere i client esistenti, inclusi gli schemi di versionamento e le regole di compatibilità. Eserciti System Design Basics for Backend Developers con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare System Design Basics for Backend Developers?
Non è richiesta alcuna esperienza precedente. System Design Basics for Backend Developers su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.
Quanto tempo richiede la lezione «Versionamento delle API e compatibilità retroattiva»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione System Design Basics for Backend Developers?
Sì. Ogni lezione System Design Basics for Backend Developers include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Principi di progettazione delle API RESTful
- GraphQL e gRPC
- Code di messaggi e architetture event-driven
- Versionamento delle API e compatibilità retroattiva