Passa al contenuto principale

4.16. Permettere il versioning e l'evoluzione

4.16. Permettere il versioning e l'evoluzione​

Uno degli aspetti più impegnativi della progettazione di un protocollo di applicazione è garantire che possa evolversi nel tempo mantenendo la compatibilità con le distribuzioni esistenti.

Le applicazioni che utilizzano HTTP DOVREBBERO progettare per l'estensibilità fin dall'inizio. Questo include:

  • Negoziazione del protocollo: Fornire meccanismi per client e server per negoziare quale versione o funzionalità utilizzare.

  • Degradazione graziosa: Consentire ai client più vecchi di funzionare con server più nuovi (e viceversa), anche se non supportano tutte le funzionalità.

  • Scoperta delle funzionalità: Consentire ai client di scoprire quali funzionalità supporta un server.

  • Ignorare elementi sconosciuti: Specificare che le implementazioni dovrebbero ignorare campi di intestazione, contenuto o altri elementi di protocollo sconosciuti piuttosto che trattarli come errori.

Gli approcci comuni al versioning includono:

  • Versioning per tipo di media: Utilizzare diversi tipi di media per diverse versioni (ad esempio, application/vnd.example.v1+json, application/vnd.example.v2+json).

  • Versioning per URL: Includere la versione nell'URL (ad esempio, /v1/resource, /v2/resource). Tuttavia, questo può creare problemi con il caching e l'identità delle risorse.

  • Versioning per campo di intestazione: Utilizzare un campo di intestazione personalizzato per indicare la versione.

  • Negoziazione basata sulle funzionalità: Piuttosto che versionare l'intero protocollo, consentire la negoziazione di singole funzionalità.

Le applicazioni DOVREBBERO:

  • Documentare chiaramente come funziona il versioning.

  • Fornire indicazioni su come mantenere la retrocompatibilità.

  • Considerare l'impatto del versioning sul caching e altre funzionalità HTTP.

  • Evitare di apportare modifiche incompatibili alle versioni esistenti; invece, definire nuove versioni quando sono necessarie modifiche incompatibili.

Le applicazioni NON DOVREBBERO:

  • Utilizzare parametri di query URL per il versioning, poiché questo può interferire con il caching.

  • Creare situazioni in cui diverse versioni del protocollo utilizzano gli stessi identificatori (URL, tipi di media) per cose diverse.

  • Forzare i client ad aggiornare immediatamente quando vengono rilasciate nuove versioni.

Ultimo aggiornamento il