Suggerimento Versione del servizio REST

Tutto si riduce al routing.

Hai due obiettivi principali

1. Vuoi che ogni versione dell'API non si preoccupi dell'esistenza di altre versioni.

2. Vuoi essere in grado di estrarre semplicemente il numero di versione dal traffico http inorder per instradare quel traffico all'istanza API corretta.

Se inserisci la versione al centro della stringa di query:

www.myservice.com/users/v1/searchByName?name=test

Implica che il servizio identificato dall'host abbia più di una versione. Gli utenti potrebbero essere v1 e i clienti potrebbero essere v2. Ciò infrange la regola 1. si desidera distribuire un servizio v1 o un servizio v2, non metà e metà.

È difficile estrarre la versione dalla stringa.

www.myservice.com/users/v1/searchByName?name=test
www.myservice.com/customer/v1/5
www.myservice.com/orders/france/v1/delivered

immagina di scrivere un modello regex per il tuo router per ottenere la versione da una qualsiasi di quelle possibili richieste.

in confronto, mettendolo all'inizio della query

• implica una singola versione per il servizio sull'host.
• è facile da estrarre dalla stringa poiché è sempre la prima parte
• può facilmente essere ignorato dal servizio stesso. Soprattutto se si sta distribuendo su directory virtuali o simili
• il client può specificarlo come parte dell'URL di base www.myservice.com/v1 e semplicemente aggiungere il percorso del metodo.

Dovrebbe essere menzionato di passaggio che mettere la versione nell'intestazione renderà i tuoi url più belli. Ma so che alcuni routing (AWS) non possono controllare l'intestazione.

I want to enable versioning in my REST service via urls.

Scelta migliore: pianificare la compatibilità nella progettazione, in modo tale che le modifiche all'implementazione non interrompano i client esistenti. Cool URI non cambia.

La prossima scelta migliore: una nuova API viene distribuita su un nuovo host. Fielding, nel 2014

It is always possible for some unexpected reason to come along that requires a completely different API, especially when the semantics of the interface change or security issues require the abandonment of previously deployed software. My point was that there is no need to anticipate such world-breaking changes with a version ID. We have the hostname for that. What you are creating is not a new version of the API, but a new system with a new brand.

<myapp_context>/v1/<sub_context>
v1/<myapp_context>/<sub_context>

Non c'è davvero molta differenza qui - vale la pena considerare se un o l'altro di questi sta per essere più utile quando i clienti eseguono una risoluzione relativa di URI.

Una cosa che ritengo sia cruciale per una strategia di versioning di successo è quella di separare molto chiaramente il controllo di versione delle strutture di dati nei tuoi payload e il controllo di versione delle operazioni di cui hai bisogno. Se confonderai queste due cose, tenderai a trovare un approccio incoerente.

Ad esempio, supponiamo che tu abbia creato un'API con endpoint:

.../<employee>/management

e l'output di dati contiene questo:

"manager": "Boss Hog"

Ora all'improvviso ti viene detto che l'organizzazione si sta spostando verso la gestione di matrici * e devi supportare questo nella tua API. Quindi modifichi il formato dei dati:

"managers": [
  {"manager": "Boss Hog", "type": "boss"}, 
  {"manager": "Rosco Pico Train", "type": "sheriff"}
]

Non rimanere impigliato nella struttura o in che modo potresti modificarlo in modo irrinunciabile. supponiamo solo per questo esempio che devi modificare la struttura in modo che alcuni client non possano gestire senza modifiche.

Si noti che l'URI per questo è sempre lo stesso. Questo è davvero cruciale perché REST (HTTP) fornisce una bella funzionalità che ti permette di supportare questo usando i tipi mime personalizzati. Ciò significa che i tuoi payload possono evolvere nel tempo mentre gli URI sono stabili.

Ora, se hai bisogno di cambiare le strutture URI, è qui che entra in gioco la tua versione di URI. Per la tua sanità mentale, ti suggerisco di fare una versione dell'intera cosa, anche se viene fatta solo una piccola modifica. Detto questo, probabilmente non vorrai preoccuparti di provare a supportare più strategie di mappatura URI nello stesso codice. Inserendo il numero di versione in precedenza nel percorso, semplifica la distribuzione di questi separatamente e utilizza un proxy inverso per risolvere le cose.

_{* Non sostengo la gestione delle matrici.}

Di solito, un'API è un sistema unico coerente. Sebbene contenga più risorse, queste sono tutte correlate. L'API è distribuita come un singolo software.

Ma non deve essere così. L'API può anche essere aggregata da più sotto-API che sono in gran parte non correlate tra loro e vengono implementate in modo indipendente. Il server API esegue quindi il routing per tradurre le richieste nella sub-API corretta.

Se la tua API è un singolo sistema, fornire una singola versione alla radice è più semplice. Questo è particolarmente vero quando non hai ancora bisogno di quella flessibilità. In particolare, questo ti consente di più tardi introdurre URL come /v2/some-sub-api/v7/foo che combinano il controllo delle versioni nella directory principale e il controllo delle versioni separato per le API secondarie. Probabilmente non sai in anticipo dove sarà necessario introdurre il versioning delle API secondarie.

Se l'API è costituita da API secondarie realmente separate (ed è anche chiaramente architettata e documentata in questo modo), allora le versioni separate possono avere senso. Ma questo introduce molta complessità nella progettazione dell'URL. A meno che la tua API non sia davvero gigantesca, potrebbe essere meglio evitarlo ed esporre un'API unificata.

Si noti che non è necessario "montare" un'API nella radice di un dominio. Cioè è perfettamente legittimo utilizzare example.com/some-app/api/<API> anziché some-app-api.example.com/<API> . Tuttavia, tieni presente che la condivisione di un dominio implica anche che ad es. cookie e altre proprietà rilevanti per la sicurezza sono condivisi. Questo può o non può essere desiderabile. Ciò è più pertinente se si suppone che le tue API vengano utilizzate tramite le richieste Ajax, meno rilevanti per le API che verranno utilizzate solo dal software personalizzato.