In un ampio servizio con più consumatori e servizi integrati, ecco alcuni principi e linee guida che abbiamo seguito per essere RESTful sulla nostra web API. Se non stai cercando di essere RESTful ecc ... e vuoi semplicemente un semplice http api, allora potrebbe non essere applicabile.
Principi chiave:
- Una risorsa è identificata da un URL RESTful (site.com/api/user/6).
- Quell'URL deve essere un permalink (si riferisce sempre a quella risorsa). I servizi esterni e i consumatori dell'API possono persistere in permalink
- Diverse versioni del client potrebbero richiedere site.com/api/user/6 e, a seconda della versione, potrebbero ottenere una rappresentazione (versione) diversa della risorsa.
- Ci impegniamo a farlo bene, a rivedere le API, ecc ... ma ci rendiamo conto che a volte non ci riusciamo e vogliamo la possibilità di essere in grado di farlo funzionare e di farlo funzionare correttamente.
Abbiamo preso in considerazione la possibilità di inserire la versione nell'URL, ma ciò infrange i principi fondamentali RESTful.
link
Buona lettura su web api design e versioning
Cosa abbiamo fatto (in pratica, agitando le mani sui dettagli):
- Inserisci la versione della richiesta nell'intestazione tipo accept / content usando le proprietà del tipo MIME: application / json; version = 2 (abbiamo considerato i tipi MIME del fornitore che BTW, github utilizza ). Supportiamo anche il passaggio in querystring per scenari di mashup web.
- Abbiamo personalizzato il routing in modo che una richiesta per la versione 2 della richiesta di risorsa si collegasse al 2Controller (risorse).
- In una richiesta http OPTIONS, il server eseguirà iterazioni sulle rotte ed esporrà le risorse, i modelli di percorso disponibili e la versione minima / massima (il nostro attributo personalizzato inserito nel controller / classi).
- Il client sa quale versione è, quindi la prima cosa che il client ha fatto è una richiesta OPTIONS e ha negoziato la versione massima che il client e il server comprendono, quindi l'avrebbe inviata nell'intestazione.
- Poiché il server ha più controller, è in grado di restituire versioni differenti di tale risorsa.
- Anche se siamo in grado di eseguire il versioning della risorsa, ci asteniamo e adottiamo un approccio puramente additivo, se possibile (i client più vecchi ignorano le proprietà extra sulla deserializzazione). iOS farà questo bene dato che sono solo dati extra nei dizionari.
- Uno dei vantaggi che abbiamo ottenuto dalle OPZIONI che espongono le rotte, è che in realtà evitiamo i percorsi matematici sul client. Sa quale versione è - il client http passa in un dizionario e gli URL sono formattati usando i percorsi pubblicizzati dal server.
Sto pensando di scrivere un blog e di condividere il modo in cui abbiamo integrato in web api la versione delle nostre risorse. Se lo faccio, seguirò qui con un link.