Vendor MIME-Typen (für API-Version)

Question

Ich habe viele der Stack Overflow (und andere) Beiträge auf Versionierung RESTful Dienste gelesen. Es ist ein bisschen überwältigend, um ehrlich zu sein.

Ich habe beschlossen, einen Accept: Header für unseren (marginal) RESTful Service zu verwenden, damit Clients bestimmte Versionen einer Ressource anfordern können. Was mir nicht klar ist, ist, was ich im Accept-Header festlegen soll.

Das Beispiel habe ich oft gesehen habe, ist dies:

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

Meine Fragen sind:

1. Bin ich richtig, dass alle VND Arten registriert werden müssen? (http://www.iana.org/cgi-bin/mediatypes.pl)

2. Sind die Version und der Typ (d. H. -v2 + json) Teil des Typs und so müssen jede Version und jeder Typ registriert werden?

3. Gibt es einen Grund, vnd anstelle eines "x-" Subtyps zu verwenden, der nicht registriert werden muss? Zum Beispiel:

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

   Die vorhandene API ist nur intern, wird aber in Zukunft für Kunden verfügbar sein.

4. Nicht sicher, das macht Sinn, aber ist es möglich, einen vorhandenen Typ zu verwenden, aber eine Version hinzuzufügen? (Die aktuelle API gibt "application/json")

   Accept: application/json-v2 
   

5. Was sind akzeptabel Formate zum Anfügen eine Version und die Art (z.B. -V2 + json).

6. Was ist, wenn ein Client nach einer nicht unterstützten Version fragt? Ist die richtige Antwort eine 406? Kann der Kunde eine Version anfordern? Oder allgemeiner, was ist, wenn der Client keinen Accept-Header oder Accept: */* anbietet?

Alle zusätzlichen Vorschläge willkommen. Das Ziel besteht natürlich darin, Änderungen an dem zuzulassen, was der Dienst für eine bestimmte Ressource zurückgibt, aber keine bestehenden Clients zu unterbrechen.

Hier ist eine kurze Liste von Ressourcen, die ich in letzter Zeit haben gesucht:

• 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

Als ich den jsonapi.org Standard folgen entschieden habe, habe ich beschlossen, genau das, was Ihr Beispiel zeigt, zu tun.

In Bezug auf Ihre Fragen:

1. sollte Ihr MIME-Typ
2. ich, dass jede Version und die Art, wie sie einzigartige Arten
3. x- Präfix wie bereits erwähnt wurde als veraltet sind registriert sollte glauben registriert werden Kommentar
4. application/json-v2 würde 415 Unsupported Media Type keine Gültigkeit
5. Sie zurückkehren konnten oder einfach 400 Bad Request