Versioning REST APIs. Ogni API ha una sua versione

Quelle che chiami API di singole REST potrebbero essere chiamate particolari set di risorse o risorse dell'API REST. Puoi anche considerarlo come una funzionalità dell'API REST. Come qualsiasi tipo di software, l'intero pacchetto è aggiornato / aggiornato, non singole funzionalità o risorse.

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

Quindi, per quanto vedo, i principali svantaggi della tua convenzione di denominazione di ricerca delle risorse proposta:

• Per l'utente API , risulterebbe in localizzatori di risorse molto più complessi, meno prevedibili, meno memorizzabili e meno stabili. È difficile ricordare quale versione particolare si trova su ogni singola risorsa e insieme di risorse ...
• Per gli sviluppatori di moduli , è ora più lavoro avere a che fare con questo versioning in il proprio resource locator.
• Le modifiche ai localizzatori di risorse diventano molto più frequenti, in quanto vi sono più moduli in aggiornamento ... A lungo termine, i contro precedenti potrebbero diventare spiacevoli ...

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

Potresti trovare un modo migliore per introdurre una modifica innovativa o addirittura eseguire il versioning dell'API REST con forse un'intestazione HTTP?
Per saperne un po 'di più sull'approccio delle intestazioni HTTP, vedere altre risposte di seguito e: link

Ecco un approccio ancora migliore: utilizza negoziazione del contenuto per eseguire la versione dell'API con le intestazioni Content-Type e 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, è sufficiente richiederla con un tipo di contenuto diverso in Accept . In questo modo, le versioni specifiche supportate dal server sono completamente indipendenti dalla struttura dell'URL. Lo stesso server può supportare più versioni semplicemente selezionando a cui rispondere in base all'intestazione Accept . In alternativa, se desideri utilizzare diverse distribuzioni per versioni diverse, potresti mettere un proxy di fronte a diverse versioni del tuo servizio che ha scelto quale inoltrare richieste in base all'intestazione Accept .

Ciò consente anche di supportare nuovi formati con differenti semantiche (non solo versioni diverse) sugli stessi endpoint. Ad esempio, il POST di un elenco di account su /api/accounts potrebbe significare la creazione di lotti e non sarebbe necessario creare un endpoint API separato per questo.

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

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 il mio cambiamento non influisce sul fatto che" bene ti troverai nei guai quando commetti un errore.

Inoltre, vorrai avere entrambe le versioni v1 e v2 della tua API distribuite allo stesso tempo. Ciò avviene normalmente distribuendo ciascuna versione su un server separato e indirizzando il traffico di conseguenza.

Se non hai una versione API singola, diventa molto più complessa.