Versioning REST API di un'applicazione ASP.NET MVC

Question

Sto cercando di sviluppare un'applicazione in ASP.NET MVC 3 e vorrei fornire un'API pubblica allo stesso tempo.

Dal guardarsi intorno, sembra che ci siano 2 modi per farlo. Creare un'area API e disporre di controller che restituiscano json/xml. Oppure utilizzare i filtri azione e un singolo set di controller front-end e restituire json/xml/html in base alle intestazioni delle richieste.

Mi piacerebbe fare il dopo, ma mi stavo chiedendo come si può andare sulla versione della propria API se si è andati questa rotta?

Se si passa al primo percorso, è possibile creare semplicemente un controller v1/v2, ma se lo si fa in un secondo momento, come è possibile farlo?

Answer 1

È possibile percorrere uno dei due percorsi: è possibile includere l'API nel percorso (anziché http://app.lication/category/1 si avrà qualcosa come http://app.lication/api/v1/category/1) oppure è possibile includere uno custom HTTP header.

In entrambi i casi è possibile discriminare quale versione viene chiamata.

Answer 2

Il controllo delle versioni è un problema piuttosto complesso. Qui ci sono modi che ho guardato prima:

1. URL. In questo caso si presume che https://api.example.com/v1/projects sia una risorsa diversa da http://api.example.com/v2/projects, anche se non è il caso. Basecamp sembra fare questo. Seguendo questo approccio, supponi che dovrai sempre supportare le vecchie API.
2. Intestazioni. Gli URL rimangono gli stessi, tuttavia, il client passa un'intestazione HTTP aggiuntiva, ad esempio X-MYAPI-VERSION con ogni richiesta con un valore che identifica la versione dell'API da utilizzare. Lo Google Documents List API fa questo. Un potenziale problema con questo approccio è che le intestazioni HTTP possono essere rimosse dagli intermediari tra il client e il server.
3. Parametri. Per aggirare il problema con l'opzione 2, è possibile passare la versione dell'API da utilizzare come parametro (ad esempio https://api.example.com/projects?v=3).
4. Tipi di supporto. Qui gli URL rimangono invariati, tuttavia, gli utenti sono tenuti a specificare la rappresentazione delle risorse utilizzando le intestazioni di tipo Accetto e Contenuto. Ad esempio, un "progetto" può essere presentato utilizzando "application/vnd.mycompany.resource [-version] [+ format]" fornendo le rappresentazioni di "application/vnd.mycompany.project-v1 + json" per v1 json o " application/vnd.mycompany.project-v1 + xml "per v1 xml. Quando hai bisogno di una nuova versione di un progetto, il tipo mime può apparire come segue "application/vnd.mycompany.project-v2 + xml". Github sembra supportarlo.
5. Parte del carico utile. In questo caso il carico utile della richiesta contiene il numero di versione da utilizzare. Ad esempio, quando viene passato XML, è possibile esaminare lo spazio dei nomi per determinare quale versione dell'API viene utilizzata. Per JSON, è possibile utilizzare una proprietà "$ version" o "_version" per specificare la versione.
6. Chiave cliente. Quando l'applicazione è registrata, specifica quale versione dell'API vuole utilizzare. Quando si autentica il client, si garantisce di emulare la versione che desidera utilizzare.
7. Nessun controllo delle versioni esplicito Esiste sempre l'opzione di non eseguire la versione dell'API e provare a gestire le modifiche in modo trasparente rendendo tutti i campi opzionali e gestendoli in modo appropriato quando mancano. È probabile che lo farai comunque per rendere le versioni future della tua API compatibili con la versione che stai sviluppando oggi.

Molti consigliano l'opzione 4, sebbene non sia sempre pratica. Molte di queste opzioni richiedono un lavoro aggiuntivo per lavorare con ASP.NET MVC.