Tipi MIME del fornitore (per il controllo delle versioni API)

Question

Ho letto molti degli overflow dello stack (e di altri) sui servizi RESTful di versioning. È un po 'travolgente, ad essere onesti.

Ho deciso di utilizzare un'intestazione Accept: per il nostro servizio (marginalmente) RESTful in modo che i client possano richiedere versioni specifiche di una risorsa. Quello su cui non sono chiaro è cosa specificare nell'intestazione Accept.

L'esempio che ho visto spesso è questa:

Accept: application/vnd.mycompany.myapp.customer-v2+json 

Le mie domande sono:

1. Sono corretto che tutti i tipi VND devono essere registrati? (http://www.iana.org/cgi-bin/mediatypes.pl)

2. La versione e il tipo (cioè -v2 + json) fanno parte del tipo e quindi è necessario registrare ogni versione e tipo?

3. C'è qualche motivo per usare vnd invece di un sottotipo "x-" che non ha bisogno di essere registrato? Ad esempio:

   Accept: application/x-mycompany.myapp-v2+json 
   

   L'API esistente è solo interna, ma in futuro sarà esposta ai clienti.

4. Non è sicuro che ciò abbia senso, ma è possibile utilizzare un tipo esistente ma aggiungere una versione? (L'API corrente restituisce "application/json")

   Accept: application/json-v2 
   

5. Quali sono formati accettabili per aggiungendo una versione e del tipo (ad esempio -v2 + JSON).

6. Cosa succede se un client richiede una versione non supportata? La risposta corretta è 406? Il cliente può richiedere qualsiasi versione? O più in generale, cosa succede se il client non fornisce l'intestazione Accept o Accept: */*?

Qualsiasi suggerimento aggiuntivo benvenuto. L'obiettivo, ovviamente, è quello di consentire modifiche a ciò che il servizio restituisce per una determinata risorsa, ma non a rompere i client esistenti.

Ecco un breve elenco di risorse Ho guardato di recente:

• Best practices for API versioning?
• How to version REST URIs
• REST api versioning (only version the representation, not the resource itself)
• http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/
• http://www.subbu.org/blog/2008/05/avoid-versioning-please
• http://www.informit.com/articles/article.aspx?p=1566460
• http://en.wikipedia.org/wiki/Internet_media_type#Prefix_vnd
• http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1

Answer 1

Come ho deciso di seguire lo standard jsonapi.org, ho deciso di fare solo ciò che il vostro esempio mostra.

quanto riguarda le vostre domande:

1. tuo tipo MIME deve essere registrato
2. Credo che ogni versione e tipo devono essere registrati, in quanto sono tipi unici
3. x- prefisso è stato deprecato come indicato in un commento
4. application/json-v2 non sarebbe valido
5. Si potrebbe tornare 415 Unsupported Media Type o semplicemente 400 Bad Request