API REST di controllo delle versioni. Ogni API ha la sua versione

È molto comune specificare la versione delle API REST nell'URL, in particolare all'inizio del percorso, ovvero qualcosa del tipo:

POST /api/v1/accounts
GET /api/v1/accounts/details

Tuttavia, non ho visto alcun design in cui la versione è associata a ciascuna API. In altre parole, manteniamo la versione di ciascuna API separatamente. vale a dire:

POST /api/accounts/v2
GET /api/accounts/details/v3

Utilizzando questo approccio incrementiamo la versione dell'API dell'API specifica quando è necessaria la modifica definitiva, non è necessario incrementare la versione dell'intera API.

Quali sono gli svantaggi dell'utilizzo di questo stile invece dello stile comune?

— Eng.Fouad
fonte

Risposte:

Le cosiddette API REST singole potrebbero essere chiamate insieme specifico di risorse o risorse dell'API REST . Potresti anche guardarlo come funzionalità dell'API REST . Come ogni tipo di software, l'intero pacchetto è versionato / aggiornato, non singole funzionalità o risorse.

La tua domanda avrebbe senso nel contesto in cui le risorse del pacchetto API REST sono modulari e potenzialmente potenzialmente sviluppate e aggiornate separatamente.

Quindi, per quanto vedo, i principali svantaggi della convenzione sulla denominazione del localizzatore di risorse proposta sono:

Per l' utente API , si tradurrebbe in localizzatori di risorse molto più complessi, meno prevedibili, meno memorabili e meno stabili.
Per gli sviluppatori di moduli , ora è più lavoro dover gestire questo controllo delle versioni nel proprio localizzatore di risorse.
I cambiamenti nei localizzatori di risorse diventano molto più frequenti, in quanto vi sono aggiornamenti di più moduli, quindi i contro sopra sono esponenziali ...

Quando si crea un'API, uno dei tuoi obiettivi principali è renderlo facile da usare ...

Potresti trovare un modo migliore per introdurre una modifica sostanziale o persino il controllo delle versioni dell'API REST con forse un'intestazione HTTP?

Per saperne di più sull'approccio delle intestazioni HTTP, vedere le altre risposte di seguito e: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

— Clemc
fonte

Ecco un approccio ancora migliore: usa la negoziazione dei contenuti per versioni della tua API con le intestazioni Content-Typee Accept:

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

Per ottenere una versione diversa, basta richiederla con un diverso tipo di contenuto Accept. In questo modo, le versioni specifiche supportate dal server sono completamente indipendenti dalla struttura dell'URL. Lo stesso server potrebbe supportare più versioni semplicemente selezionando con quale rispondere in base all'intestazione Accept. In alternativa, se si desidera attenersi a distribuzioni diverse per versioni diverse, è possibile mettere un proxy davanti a diverse versioni del servizio che ha scelto quale inoltrare le richieste in base all'intestazione Accept.

Ciò consente anche di supportare nuovi formati con semantica diversa (non solo versioni diverse) sugli stessi endpoint. Ad esempio, POSTARE un elenco di account /api/accountspuò significare la creazione in batch e non è necessario creare un endpoint API separato per esso.

— Jack
fonte

omg l'intestazione accetta deve essere la scelta peggiore per la segnalazione della versione. utilizzare un'intestazione della versione, se possibile, url path se necessario (ad es. routing AWS)

— Ewan,

@Ewan Why? Un'intestazione di versione personalizzata implica che versioni diverse sono la stessa risorsa senza informare gli intermediari che il contenuto potrebbe essere diverso. Un proxy di memorizzazione nella cache non saprebbe usare l'intestazione per non servire le risposte memorizzate nella cache v1 alle richieste v2.

— Jack,

utilizzare l'intestazione di risposta variabile, se non si sta già utilizzando no-cache per le richieste API !. il tipo di contenuto ha già un significato, sostituirlo per uso privato rende la vita difficile ai consumatori

— Ewan,

@Ewan Ecco a cosa servono la vndparte e la +sintassi del tipo: per indicare questo è un sottotipo specifico del fornitore del application/jsontipo. Questo è esattamente ciò per cui sono progettati i tipi di contenuto. La tua risorsa è disponibile in più formati. Stai chiedendo al cliente di scegliere quale formato desidera. Inoltre, non vi è alcun motivo per cui le richieste API non possano utilizzare la semantica della cache HTTP standard.

— Jack,

se correggi un bug in myapi v2 non stai restituendo un nuovo tipo mime.

— Ewan,

La cosa fondamentale è che se si esegue la versione di ciascun endpoint separatamente, è necessario poter distribuire ciascun endpoint separatamente.

Le API di solito hanno una versione perché tutti gli endpoint sono nella stessa base di codice e quindi hanno dipendenze condivise e sono distribuiti insieme.

Se non stai aggiornando la versione quando apporti una modifica perché "Oh, sono abbastanza sicuro che la mia modifica non influisca su quello", avrai dei problemi quando commetti un errore.

Inoltre, vorrai distribuire contemporaneamente v1 e v2 dell'API. Ciò avviene normalmente distribuendo ciascuna versione su un server separato e instradando il traffico di conseguenza.

Se non disponi di un'unica versione API, questo diventa molto più complesso.

— Ewan
fonte