Come versione di RIPOSO Uri

Question

Qual è il modo migliore per versione RIPOSO Uri?Attualmente abbiamo una versione # in URI stesso, vale a dire.

http://example.com/users/v4/1234/

per la versione 4 di questa rappresentazione.

La versione appartengono in queryString?ie.

http://example.com/users/1234?version=4

O è il controllo delle versioni migliori compiuto un altro modo?

Answer 1

Direi che la rende parte di URI stesso (opzione 1) è il migliore perché v4 identifica una risorsa diversa rispetto a v3.I parametri di Query, come nella tua seconda opzione può essere meglio utilizzato per il passaggio di ulteriori (query) informazioni relative all' richiesta, piuttosto che il risorsa.

Answer 2

Non URL versione, perché ...

• rompi permalink
• I cambiamenti URL sarà diffusa come una malattia attraverso l'interfaccia. Che cosa fate con le rappresentazioni che non sono cambiati, ma punto alla rappresentazione che ha? Se si cambia l'url, si rompe i vecchi clienti. Se si lascia l'url, i tuoi nuovi clienti potrebbero non funzionare.
• Versioning tipi di media è una soluzione molto più flessibile.

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 vostri clienti V1 e V2 possono coesistere pacificamente.

In un'interfaccia RESTful, la cosa più vicina si dispone di un contratto è la definizione dei media-tipi che vengono scambiati tra il client e il server.

Gli URL che il client utilizza per interagire con il server dovrebbero essere forniti dal server incorporato nelle rappresentazioni recuperati in precedenza. L'unico URL che deve essere conosciuto con il cliente è l'URL principale dell'interfaccia. L'aggiunta di numeri di versione per gli URL ha valore solo se si costruisce gli URL sul client, che non si supponga di fare con un'interfaccia RESTful.

Se è necessario apportare una modifica alle tipo di media che si romperà vostri clienti esistenti quindi creare una nuova e lasciare i tuoi URL da solo!

E per quei lettori attualmente dicendo che questo non ha senso se sto usando application / xml e application / json come tipo di media. Come dovremmo versione quelli? Tu non sei. Quei media-tipi sono praticamente inutile ad un'interfaccia RESTful meno che non li analizza utilizzando il codice-download, a quel punto il controllo delle versioni è un punto controverso.

Answer 3

Ah, sto mettendo il mio vecchio cappello scontroso di nuovo.

Dal punto di vista di riposo, non importa affatto. Non una salsiccia.

Il client riceve un URI si vuole seguire, e lo tratta come una stringa opaca. Mettere quello che vuoi in esso, il cliente ha non conoscenza di una cosa come un identificatore di versione su di esso.

Quello che il cliente sa è che può elaborare il tipo di supporto, e io consiglierei di seguire il consiglio di Darrel. Anche Personalmente ritengo che la necessità di cambiare il formato utilizzato in un'architettura riposante 4 volte dovrebbero portare enormi segni premonitori di massa che si sta facendo qualcosa di seriamente sbagliato, e bypassando completamente la necessità di progettare il tipo di supporto per il cambiamento resiliance.

Ma in entrambi i casi, il cliente può elaborare solo un documento con un formato che può capire e seguire i link in essa. E 'necessario conoscere i rapporti di collegamento (le transizioni). Allora, qual è l'URI è del tutto irrilevante.

Io personalmente voterei 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 mi permetto di suggerire che, dal punto di vista del server, è shouldn' t hanno 4 versioni, ma 4 tipi di media).

Answer 4

non dovrebbe mettere la versione nella URL, si dovrebbe mettere la versione nella Accetta intestazione della richiesta - vedi il mio post su questo thread:

Le migliori pratiche per il controllo delle versioni API?

Se si inizia attaccando versioni nell'URL si finisce con gli URL stupide come questa: http://company.com/api/v3 0,0 / cliente / 123 / v2.0 / ordini / 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-e-tipi-in-resthttp-API.html

Answer 5

Questi (meno-specifico) SO domande su REST API delle versioni possono essere utili:

• Versioning servizi RESTful?
• Le migliori pratiche per web service REST API delle versioni

Answer 6

Se i servizi REST richiedono l'autenticazione prima dell'uso, si potrebbe facilmente associare la chiave API / gettone con una versione API e fare il percorso internamente. Per utilizzare una nuova versione delle API, potrebbe essere richiesta una nuova chiave API, legata a quella versione.

Sfortunatamente, questa soluzione funziona solo per le API auth-based. Tuttavia, non tenere le versioni fuori degli URI.

Answer 7

Ho voluto creare API di versione e ho trovato questo articolo molto utile:

http: //blog.steveklabnik. com / messaggi / 2011-07-03-nessuno-capisce-resto-o-http

C'è una piccola sezione su "Voglio che la mia API da versioned". L'ho trovato semplice e facile da capire. Il punto cruciale è quello di utilizzare accettare campo nell'intestazione di trasmettere informazioni sulla versione.

Answer 8

Ci sono 4 diversi approcci al versioning API:

• Aggiunta versione al percorso URI:

  http://example.com/api/v1/foo
  
  http://example.com/api/v2/foo
  

    

  Quando si dispone di modifica sostanziale, è necessario incrementare la versione come: v1, v2, v3 ...

  È possibile implementare un controller in voi codice come questo:

  @RestController
  public class FooVersioningController {
  
  @GetMapping("v1/foo")
  public FooV1 fooV1() {
      return new FooV1("firstname lastname");
  }
  
  @GetMapping("v2/foo")
  public FooV2 fooV2() {
      return new FooV2(new Name("firstname", "lastname"));
  }
  

• parametro della richiesta delle versioni:

  http://example.com/api/v2/foo/param?version=1
  http://example.com/api/v2/foo/param?version=2
  

    

  Il parametro versione può essere opzionale o necessario a seconda di come si desidera che l'API da utilizzare.

  L'implementazione può essere simile a questo:

  @GetMapping(value = "/foo/param", params = "version=1")
  public FooV1 paramV1() {
      return new FooV1("firstname lastname");
  }
  
  @GetMapping(value = "/foo/param", params = "version=2")
  public FooV2 paramV2() {
      return new FooV2(new Name("firstname", "lastname"));
  }
  

• Il passaggio di un header personalizzato:

  http://localhost:8080/foo/produces
  

  Con intestazione:

  headers[Accept=application/vnd.company.app-v1+json]
  

  o

  headers[Accept=application/vnd.company.app-v2+json]
  

    

  più grande vantaggio di questo sistema è per lo più semantica: non ingombrano l'URI con nulla a che fare con il controllo delle versioni

  .

  Possibile applicazione:

  @GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v1+json")
  public FooV1 producesV1() {
      return new FooV1("firstname lastname");
  }
  
  @GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v2+json")
  public FooV2 producesV2() {
      return new FooV2(new Name("firstname", "lastname"));
  }
  

• Modifica nomi host o utilizzando gateway API:

    

  In sostanza, si sta spostando l'API da un nome host ad un altro. Si potrebbe anche solo chiamare questo edificio una nuova API per le stesse risorse.

       

  Inoltre, è possibile farlo utilizzando gateway API.

Answer 9

Mi piacerebbe includere la versione come valore opzionale alla fine del URI. Questo potrebbe essere un suffisso come / V4 o di un parametro di query come hai descritto. Si potrebbe anche reindirizzare l'/ V4 per il parametro di query in modo da supportare entrambe le varianti.

Answer 10

Se si utilizzano URI per il controllo delle versioni, quindi il numero di versione dovrebbe essere nella URI della radice API, in modo che ogni identificatore di risorsa può includerla.

Tecnicamente un API REST non si rompe da cambiamenti URL (il risultato del vincolo un'interfaccia uniforme). Si rompe solo quando i relativi semantica (per esempio una specifica RDF vocab API) cambia in modo non compatibile all'indietro (rare). Attualmente un sacco di ppl non utilizzare i collegamenti per la navigazione (hateoas vincolo) e vocabs per annotare le loro risposte riposo (messaggio vincolo auto-descrittivo) è per questo che i loro clienti si rompono.

tipi personalizzati MIME e il tipo MIME delle versioni non aiuta, perché mettere il relativi metadati e la struttura della rappresentazione in una breve stringa non funziona. Ofc. i metadati e la struttura frequentemente cambiare, e così il numero di versione troppo ...

Quindi, per rispondere alla tua domanda il modo migliore per annotare le vostre richieste e le risposte con vocabs ( Hydra , dati collegati ) e dimenticare versioning o usarlo solo da cambiamenti vocab compatibili con versioni precedenti non (per esempio, se si desidera sostituire un vocabolario con un altro).

Answer 11

Io voto per fare questo in tipo MIME, ma non in URL. Ma la ragione non è la stessa di altri ragazzi.

Credo che l'URL deve essere univoco (ad eccezione di quelle redirect) per localizzare la risorsa unica. Quindi, se si accetta /v2.0 negli URL, il motivo per cui non è /ver2.0 o /v2/ o /v2.0.0? O anche -alpha e -beta? (Allora diventa del tutto il concetto di semver )

Quindi, la versione in tipo MIME è più accettabile che l'URL.