Il modo più comune: penso che sia "versione prima, risorse dentro". Almeno l'ho visto in API di diversi social network. E non ho mai visto l'altro modo.
È l'unico modo logico di due: ci sono risorse all'interno (diverse versioni di) API, non API all'interno di risorse. È più facile rilasciare le versioni precedenti in questo modo: basta rispondere con 404 a tutte le richieste di subresources, fornendo un messaggio come "Questa versione dell'API non esiste più" - che rende chiaro che non è solo un refuso nell'URL. Per questo motivo, penso che sia anche molto più facile da mantenere, almeno nei framework che ho usato: aggiungerei semplicemente un'altra regola nel mio router, che corrisponde a tutte le versioni precedenti e risponde correttamente.
Quindi, nella mia esperienza, la prima versione (prima la versione, risorse interne) è l'unica che ho visto in uso, ed è molto più facile da mantenere.
Il controllo delle versioni basato sull'intestazione (ad esempio Accept: application/vnd.service.v2+json ) è molto diverso dall'annidamento dell'URL: versione di un'intera API e versioning di una singola entità. Le modifiche all'API possono includere l'aggiunta, lo spostamento e l'eliminazione di risorse, che non è qualcosa che puoi descrivere efficacemente usando una versione di entità.
Inoltre, REST richiede HATEOAS (vedi Richardson Maturity Model per una spiegazione approfondita di questo), che sarebbe difficile (o impossibile) implementare con il controllo delle versioni basato sull'intestazione. Ad esempio, è persino possibile inserire versioni basate sull'intestazione in HAL ? Dovresti inventare un modo per aggiungere la versione ai link, che probabilmente richiederebbe un formato personalizzato (non URL).
Alcuni pensano che sia vero il contrario , ma non sono d'accordo, perché non si tratta di risorse di versioning, ma piuttosto versionare l'intera API. Tutte le risorse all'interno di ciascuna versione di un'API hanno la stessa versione, indipendentemente dal fatto che tali risorse siano le stesse delle versioni precedenti.
Spero che tu non stia confondendo il pattern URL, con il file system.
Il pattern URL è flessibile e dove (e come) il tuo codice sorgente è scritto o strutturato è completamente diverso.
Non dovresti confondere i due.
Come per la convenzione, è comune usare il gestore di versione prima il nome della risorsa (o collezione): http://www.example.com/api/v1/books/ per esempio. Questa è la migliore pratica, come dimostrato dalla maggior parte delle apis pubbliche di REST. Puoi anche scegliere di modificare la tua API in modo diverso; ad esempio api/2014-01/books/ o api/1.0.1/books ecc.
L'eccezione degna di nota è facebook che ha la versione come parametro facoltativo nell'URL, ?v=1 .
Dovresti mantenere il numero di versione il più a sinistra dell'URI possibile, poiché questo gli offre l'ambito più elevato.
In ogni caso, dovresti sempre documentare correttamente le versioni dell'API e se esiste una modifica incompatibile all'indietro, documentalo e dai agli sviluppatori la possibilità di migrare.
Leggi altre domande sui tag api conventions project-structure