Poiché i servizi si distribuiscono in modo indipendente, non puoi mai presumere che i client si aggiornino in sincronia. API versioning più backward compatibility permettono ai produttori di evolversi senza rompere i consumer esistenti.
Poiché i servizi si distribuiscono in modo indipendente, non puoi mai presumere che i client si aggiornino in sincronia. API versioning più backward compatibility permettono ai produttori di evolversi senza rompere i consumer esistenti.
| Strategia | Esempio |
|---|
| URI path | GET /v2/orders/42 |
| Header | Accept: application/vnd.api.v2+json |
| Schema evolution | aggiungi campi, non rimuovere/rinominare mai |
NON-BREAKING (safe):
✓ add a new optional field
✓ add a new endpoint
✓ add a new enum value (if clients tolerate unknowns)
BREAKING (needs a new version):
✗ remove or rename a field
✗ change a type or make a field required
✗ change semantics of an existing field
message Order {
string id = 1;
double total = 2;
string currency = 3; // NEW field 3 — old clients ignore it safely
}
I numeri di campo, non i nomi, definiscono il wire format, quindi aggiungere campi è compatibile all'indietro.
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
Non rimuovere mai una versione mentre il traffico reale la usa ancora. Traccia l'utilizzo prima di ritirarla.
La distribuzione indipendente funziona solo se un produttore può rilasciare un cambiamento senza coordinare la release di ogni consumer.
Progettare per il cambiamento additivo e supportare versioni vecchie durante la migrazione è ciò che preserva quell'indipendenza invece di forzare fragili upgrade big-bang.