Dostawcy typów MIME (dla wersji API)

Question

Przeczytałem wiele postów związanych z przepełnieniem stosu (i innych) w wersjach usług RESTful. To trochę przytłaczające, szczerze mówiąc.

Postanowiłem użyć nagłówka Accept: dla naszej (minimalnie) usługi RESTful, aby klienci mogli żądać określonych wersji zasobu. To, co nie jest jasne, to, co określić w nagłówku Accept.

Przykładem często widziałem to:

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

moje pytania są następujące:

1. Czy mam rację, że wszystkie rodzaje VND muszą być zarejestrowane? (http://www.iana.org/cgi-bin/mediatypes.pl)

2. Czy wersja i typ (tj. -v2 + json) są częścią typu, a więc każda wersja i typ musiałaby zostać zarejestrowana?

3. Czy istnieje jakiś powód użycia vnd zamiast podtypu "x-", który nie musi być zarejestrowany? Na przykład:

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

   Istniejący interfejs API jest tylko wewnętrzny, ale w przyszłości będzie dostępny dla klientów.

4. Nie wiesz, czy to ma sens, ale czy można użyć istniejącego typu, ale dodać wersję? (Obecne API zwraca "application/json")

   Accept: application/json-v2 
   

5. Co dopuszczalne formaty dodanie wersję i typ (np -v2 + json).

6. Co się stanie, jeśli klient poprosi o wersję nieobsługiwaną? Czy poprawna odpowiedź to 406? Czy klient może zażądać dowolnej wersji? Lub bardziej ogólnie, co jeśli klient nie dostarczy nagłówka Accept lub Accept: */*?

Wszelkie dodatkowe sugestie są mile widziane. Celem jest oczywiście umożliwienie zmiany tego, co usługa zwraca dla danego zasobu, ale nie może złamać istniejących klientów.

Oto krótka lista zasobów Szukałem w ostatnim czasie:

• 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

Jak już postanowił pójść ze standardu jsonapi.org, postanowiłem zrobić to, czego Twój przykład pokazuje.

Odnośnie pytania:

1. Twój typ MIME powinien zostać zarejestrowany
2. Wierzę, że każda wersja i typ powinien być zarejestrowany, ponieważ są one unikalne rodzaje
3. x- prefiks została zaniechana, jak wspomniano w komentarz
4. application/json-v2 nie byłby ważny
5. można powrócić 415 Unsupported Media Type lub po prostu 400 Bad Request