Quali sono i pro e contro i metodi di versioning API

Question

In alcuni esempio ho notato due modi di versioni di un'API.

Uno di questi è usare una versione nell'URL

/api/v1/products

L'altro sta utilizzando l'intestazione del tipo di contenuto e l'intestazione accetta per contrassegnare la versione API per i dati inviati al server

Content-Type=application/vnd.company.v2+xml

Quali sono i pro e contro di questi approcci? Quali sono alcuni casi d'uso in cui utilizzerai ogni approccio?

Answer 1

Sono stato abituato ad avere il numero di versione nell'URL stesso (/v1/). Personalmente penso che questo sia un approccio molto più pulito: in questo modo, l'utente finale (o sviluppatore) non ha bisogno di gestire le intestazioni HTTP e può semplicemente modificare l'API/chiamata REST per accedere a diverse versioni dell'API secondo necessità.

Penso che sia anche possibile che alcune delle API HTTP là fuori in diverse lingue possano non avere il pieno supporto per le intestazioni HTTP, quindi fai sempre per rendere l'API più prontamente disponibile per l'utente finale. La riscrittura dell'URL è il modo più semplice e dovrebbe funzionare con tutto ciò che supporta HTTP là fuori.

Infine, consentire la specifica della versione API utilizzando l'URL consente un semplice test utilizzando un browser Web. Se si incorpora la versione in un'intestazione HTTP, lo sviluppatore è costretto a utilizzare un linguaggio di programmazione per eseguire i test.

Answer 2

Entrambi i meccanismi sono validi. Devi conoscere il tuo consumatore per sapere quale percorso seguire. In generale, lavorare con aziende e persone accademiche tende a indicare gli sviluppatori verso il controllo delle risorse. Tuttavia, se i tuoi clienti sono aziende più piccole, l'approccio di versione URL è più ampiamente utilizzato.

Ecco i pro ei contro che potrei trovare (sono sicuro che ce ne sono di più, e alcuni dei contro hanno un lavoro intorno non menzionati qui)

1. È più esplorabile. Per la maggior parte delle richieste è possibile utilizzare un browser, mentre l'implementazione dell'intestazione delle risorse richiede un approccio più programmato ai test. Tuttavia, poiché non tutte le richieste HTTP sono esplorabili, ad esempio, è necessario utilizzare un plug -in client REST come Postino o Zampa. Uri Pro/Header Con

2. Con un'API rivolta Uri, l'identificazione delle risorse e la rappresentazione della risorsa sono montate insieme. Ciò viola i principi di base del riposo; Una risorsa dovrebbe essere identificata da un endpoint e solo da un endpoint. A questo proposito, la scelta del versioning dell'intestazione delle risorse è più accademicamente idealista. Weader Pro/Uri Con.

3. Un'API con versioni Uri è meno soggetta a errori e più familiare agli sviluppatori dei clienti. La versione per URL consente allo sviluppatore di capire la versione di un servizio a colpo d'occhio. f Lo sviluppatore client dimentica di includere una versione di risorse nell'intestazione, è necessario decidere se devono essere indirizzati all'ultima versione (che può causare errori durante l'incremento della versione) o un errore 301 (spostato permanentemente). In entrambi i casi c'è più confusione per i tuoi sviluppatori di clienti più alle prime armi. Uri Pro/Header Con
4. URI Versioning si presta a Hosping più versioni nella stessa applicazione. In questo caso non è necessario sviluppare ulteriormente il tuo framework. Nota: se lo fai, la struttura della directory conterrà molto probabilmente una quantità sostanziale di codice duplicato nella directory V2. Inoltre, la distribuzione degli aggiornamenti richiede un riavvio del sistema, quindi questa tecnica dovrebbe essere evitata se possibile. Uri Pro/Header Con.
5. È più facile aggiungere il versionismo alle intestazioni HTTP per un progetto esistente che non aveva già a mente il versioni dal suo inizio. Weader Pro/Uri Con.
6. Secondo il Principio di riposo di livello 3 RMM: controlli ipermediali, è necessario utilizzare le intestazioni HTTP accetta e contenuti per gestire il controllo dei dati e descrivere i dati. Weader Pro/Uri Con.
7. Quando si inserisce la versione nell'URL, i tuoi clienti devono coordinare una modifica del loro codice (o se sono intelligenti, la loro configurazione), alla nuova API. Weader Pro/Uri Con.

Ecco alcuni link utili se vuoi fare ulteriori letture:

• La descrizione di Martin Fowler del modello di maturità di Richardson
• API Versioning - Pivotal Labs
• Hateaos
• L'articolo di Informit.com su versioni di REST SERVIZI

Answer 3

Meglio utilizzare la versione in URL. Lo stavo cercando qualche tempo fa e mi sono imbattuto nelle seguenti 2 risorse che discutono Design API RESTful Alla fine.

1. Best practice per la progettazione di un'API riposante pragmatica - Versione tramite l'URL, non tramite intestazioni.
2. programmers.stackexchange.com : Qual è un modello raccomandato per gli endpoint di riposo pianificazione per le modifiche previste?

Tl; dr Risposta: L'uso della versione # nell'URL è un approccio consigliato.

Alcune delle api più ben progettate di sempre che mi sono imbattuto- API di Instagram e API di stackoverflow.com - Entrambi usano questo approccio alla versione API.