Qual è il modo migliore per eseguire la versione URI REST? Attualmente abbiamo una versione # nell'URI stesso, es.How to version URI REST
http://example.com/users/v4/1234/
per la versione 4 di questa rappresentazione.
La versione appartiene a queryString? vale a dire.
http://example.com/users/1234?version=4
Oppure la versione è meglio realizzata in un altro modo?
Direi che renderlo parte dell'URI stesso (opzione 1) è il migliore perché v4 identifica una risorsa diversa da v3. I parametri di query come nella seconda opzione possono essere utilizzati per inoltrare informazioni aggiuntive (query) relative alla richiesta anziché alla risorsa .
Sono d'accordo con Zef ... +1! –
La domanda è: è una RISORSA diversa di cui stiamo discutendo? O una diversa rappresentazione di quella risorsa? REST fa una distinzione tra la rappresentazione e la risorsa? – Cheeso
@Cheeso - L'OP indica che è una rappresentazione diversa anziché una risorsa diversa, quindi la mia risposta. –
Includerei la versione come valore facoltativo alla fine dell'URI. Questo potrebbe essere un suffisso come/V4 o un parametro di query come hai descritto. Potresti anche reindirizzare/V4 al parametro della query in modo da supportare entrambe le varianti.
Questi (meno-specifico) SO domande su REST API delle versioni possono essere utili:
Non URL versione, perché ...
Supponendo che la risorsa sta tornando una certa variante di application/xml + vnd.yourcompany.user tutto quello che dovete fare è creare il supporto per una nuova applicazione/vnd.yourcompany.userV2 + xml tipo di supporto e attraverso la magia della negoziazione del contenuto i tuoi client v1 e v2 possono coesistere pacificamente.
In un'interfaccia RESTful, la cosa più vicina a un contratto è la definizione dei tipi di supporto scambiati tra il client e il server.
Gli URL che il client utilizza per interagire con il server devono essere forniti dal server incorporato nelle rappresentazioni recuperate in precedenza. L'unico URL che deve essere conosciuto dal client è l'URL di root dell'interfaccia. L'aggiunta di numeri di versione agli URL ha valore solo se si costruiscono URL sul client, cosa che non si suppone faccia con un'interfaccia RESTful.
Se è necessario apportare una modifica ai tipi di file multimediali che interromperanno i client esistenti, crearne uno nuovo e lasciare gli URL da soli!
E per quei lettori che stanno dicendo che questo non ha senso se sto usando application/xml e application/json come media-types. Come dovremmo interpretare quelli? Tu non sei.Questi tipi di media sono praticamente inutili per un'interfaccia RESTful a meno che non li analizzi utilizzando il download del codice, a quel punto il controllo delle versioni è un punto controverso.
Per indirizzare i punti elenco. 1. non si interrompono i collegamenti perma, perché i permalink si collegano a una versione specifica 2. Se tutto è in versione, questo non è un problema. I vecchi URL possono ancora funzionare. Idealmente, non si desidera che l'URL della versione 4 restituisca un'associazione a una risorsa versione 3. 3. Forse –
Immagina se durante l'aggiornamento a una nuova versione di un browser Web, tutti i tuoi segnalibri preferiti si rompessero! Ricorda che concettualmente l'utente sta salvando un link a una risorsa, non a una versione di una rappresentazione di una risorsa. –
@Darrel, sono d'accordo con tutto ciò che hai scritto ad eccezione del commento su xml/json media-types che è inutile per le interfacce RESTful. Puoi per favore elaborare? Non capisco cosa intendi ... – Gili
Ah, sto rimettendo il mio vecchio cappello scontroso.
Da una prospettiva ReST, non importa affatto. Non una salsiccia.
Il client riceve un URI che desidera seguire e lo tratta come una stringa opaca. Metti tutto quello che vuoi in esso, il client ha no conoscenza di una cosa come un identificatore di versione su di esso.
Ciò che il client sa è che può elaborare il tipo di supporto e consiglierò di seguire il consiglio di Darrel. Inoltre, personalmente ritengo che dover cambiare il formato utilizzato in un'architettura riposante 4 volte dovrebbe portare enormi segnali di allarme che stai facendo qualcosa di gravemente sbagliato e ignorare completamente la necessità di progettare il tuo tipo di supporto per la resilienza del cambiamento.
In ogni caso, il client può elaborare solo un documento con un formato comprensibile e seguire i collegamenti. Dovrebbe conoscere le relazioni di collegamento (le transizioni). Quindi ciò che è nell'URI è completamente irrilevante.
Io personalmente voterebbe per http://localhost/3f3405d5-5984-4683-bf26-aca186d21c04
Un identificatore perfettamente valido che impedirà ogni ulteriore sviluppatore cliente o persona che tocca il sistema di mettere in discussione se si deve mettere v4 all'inizio o alla fine di un URI (e io suggerisco che, dal punto di vista del server, non dovresti avere 4 versioni, ma 4 tipi di media).
Cosa succede se la rappresentazione deve cambiare in modo significativo e non sarà retrocompatibile? –
Progettando il tipo di supporto in modo estensibile, ad esempio utilizzando i namespace e un xsd estensibile o i formati xml esistenti ike atom, questo dovrebbe essere prevenibile. Se proprio devi, un altro tipo di supporto è la strada da percorrere. – SerialSeb
Mi piace questa risposta completamente valida, ma penso che l'URI proposto sia più per dimostrare il punto che per uno scenario reale in cui si desidera l'URI "hackerabile". –
NON dovrebbe mettere la versione nella URL, si dovrebbe mettere la versione nella Accetta intestazione della richiesta - vedi il mio post su questo thread:
Best practices for API versioning?
se si inizia attaccando le versioni del URL si finisce con gli URL stupide come questa: http://company.com/api/v3.0/customer/123/v2.0/orders/4321/
E ci sono un sacco di altri problemi che si insinuano dentro pure - vedere il mio blog: http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html
Scusa, ma non penso che finirai con URL stupidi come questo. Stai legando i numeri di versione a una particolare risorsa o (peggio) a una particolare rappresentazione. Sarebbe sciocco, IMO. Piuttosto, stai facendo il versioning dell'API, quindi non avresti mai più di una versione nell'URI. – fool4jesus
Se i servizi REST richiedono l'autenticazione prima dell'uso, è possibile associare facilmente la chiave/token dell'API a una versione API e eseguire internamente il routing. Per utilizzare una nuova versione dell'API, potrebbe essere richiesta una nuova chiave API, collegata a tale versione.
Sfortunatamente, questa soluzione funziona solo per le API basate su auth. Tuttavia, mantiene le versioni fuori dagli URI.
Ho voluto creare API di versione e ho trovato questo articolo molto utile:
http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
C'è una piccola sezione su "Voglio che la mia API da versioned". L'ho trovato semplice e facile da capire. Il punto cruciale è utilizzare il campo Accetta nell'intestazione per passare le informazioni sulla versione.
Se si utilizzano gli URI per il controllo delle versioni, il numero di versione deve trovarsi nell'URI della radice dell'API, quindi ogni identificatore di risorsa può includerlo.
Tecnicamente un'API REST non interrompe le modifiche dell'URL (il risultato del vincolo di interfaccia uniforme).Si interrompe solo quando la semantica correlata (ad esempio un vocab RDF specifico dell'API) cambia in modo non retrocompatibile (raro). Attualmente un sacco di ppl non usa link per la navigazione (vincolo HATEOAS) e vocab per annotare le loro risposte REST (limitazione del messaggio auto-descrittivo), ecco perché i loro clienti si rompono.
I tipi MIME personalizzati e il controllo delle versioni di tipo MIME non sono d'aiuto, perché non mette i metadati correlati e la struttura della rappresentazione in una stringa breve. Ofc. i metadati e la struttura cambieranno di frequente, e quindi anche il numero di versione ...
Quindi per rispondere alla tua domanda il modo migliore per annotare le tue richieste e le risposte con vocab (Hydra, linked data) e dimenticare la versione o usarlo solo con modifiche al vocabolario non retrocompatibili (ad esempio se si desidera sostituire un vocab con un altro).
Io voto per farlo in mime type ma non in URL. Ma la ragione non è la stessa di altri ragazzi.
Penso che l'URL debba essere univoco (eccetto quei reindirizzamenti) per l'individuazione della risorsa univoca. Quindi, se si accetta /v2.0 in URL, perché non è /ver2.0 o /v2/ o /v2.0.0? O anche -alpha e -beta? (quindi diventa totalmente il concetto di semver)
Quindi, la versione in mime type è più accettabile dell'URL.
Possibile duplicato di [Best practice per il controllo delle versioni API?] (Https://stackoverflow.com/questions/389169/best-practices-for-api-versioning) – Helen