Wersjonowanie REST api (tylko wersja reprezentacji, nie sam zasób)

Można Można słuchać dla X-API-Version nagłówek żądania HTTP. Jeśli nagłówek istnieje, to serwer musi używać tej wersji API. Jeśli nagłówek nie istnieje, serwer może korzystać z najnowszej wersji API.

> GET /user/123 HTTP/1.1
> Host: xxx
> X-API-Version: >=1.5.1, <2.0.0
> Accept: application/json
>

< HTTP/1.1 200 OK
< X-API-Version: 1.6.12
<
< { "user": { "id": 123, "name": "Bob Smith" } }
<

Jeśli to coś znaczy, zgadzam się z Tobą Manuel. Możesz zobaczyć moje rozumowanie w tym pytaniu Jak wersja REST URIs

Jest wiele osób, które wydają się nie zgadzać, ale nie martwiłbym się. To, jak wygląda twój adres url, naprawdę nie ma dużego wpływu na twojego klienta, o ile szanujesz ograniczenie hipertekstowe.

Zgadzam się, że nie chcesz widzieć wersji w Uri zasobów prezentowanych w Twoim API. To sprawia, że nie są "fajne". Zgadzam się również, że to jest reprezentacje, które są najbardziej prawdopodobne, aby zmienić.

Rodzi to jednak pytanie, co się stanie, gdy zmienisz zawartość danej reprezentacji. Na przykład, jeśli oryginalna reprezentacja JSON frobnitza to

{"x": "bam", "y": "hello"}

I chcesz dodać pole " z " możesz czuć, że klient powinien mieć jakieś świadomość, że jesteśmy teraz na wersji 2 jakiegoś schematu danych.

• uelastycznij swoich klientów w twarz delikatnie zmieniającym się przedstawieniem. W powyższym przykładzie nadal generujemy słownik JSON.
• jeśli musisz, umieść wersję w samej reprezentacji(pole version w tym przykładzie). W ten sposób skutecznie deklarujesz subreprezentację w typie zawartości JSON. Tak myślę. to dość ograniczające.
• Użyj własnych typów MIME i ich wersji: application/x-my-special-json1.0, application/x-my-special-json1.1. Pozwala to na wersję swoich reprezentacji niezależnie od siebie. Ponownie, z tym jednym robisz znaczne zapotrzebowanie na swoich klientów, aby wiedzieć, co się dzieje.

Ogólnie myślę, że chcesz zoptymalizować swoje API i swoje reprezentacje dla klientów, których sam nie wymyśliłeś; tych, które inni ludzie będą twórz po odkryciu swoich zasobów. Uważam, że jest to przydatne nawet w przypadku, gdy tworzysz coś, co jest prywatne, ponieważ buduje się w użytecznym ograniczeniu projektowym, które pomoże uczynić Twój system bardziej solidnym.

Znajduję http://xxxx/v1/user/123 mylące, gdyż sugeruje, że tam kiedyś będzie wyższa wersja api jak http://xxxx/v2/user/123

To nie sugeruje , że-jednak masz tę zdolność w przyszłości.

Ale to nie ma sensu w spoczynku warunki, sama wersja api to HTTP 1.0 lub 1.1, który jest już wysyłany wewnątrz żądania HTTP.

Wersja twojego API i wersja HTTP, którą jesteś używanie do składania wniosków nie musi być równe.

Można też argumentować, że taka wersja treść-negocjacje mogą być częścią URI wewnątrz ścieżki, ale znajduję intuicyjne, bo można koniec z różnymi URI dla tych samych zasobów i muszą utrzymywać przekierowuje w pewnym momencie.

Dobrze jest mieć wersję jako parametr URI, jak pokazałeś.

Http://xxx/user/123?v=1 - > for perma-links / hyperlinks

Innym podejściem może być stwierdzenie, że "jedna reprezentacja ma wiele API":

http://xxx/user/123/api/1.json

I jeśli chcesz, możesz zwrócić reprezentację za pomocą najnowszego API, gdy żądasz w ten sposób:

http://xxx/user/123.json

Osobiście bardziej lubię inne rozwiązania, ale jest to kolejne podejście, którego jeszcze nie widziałem.

Dla reszty, to, o czym większość odpowiedzi zapomina, to element danych. Zakładam, że wiele wersji API nadal współdzielą tę samą warstwę danych. Oznacza to, że warstwa danych zmusza do myślenia w sposób zgodny wstecz. Duże zmiany, które należy wprowadzić, są możliwe tylko wtedy, gdy API zmieni się w sposób zgodny wstecz. W praktyce oznacza to, że dodatkowe właściwości są dodawane po cichu do twoich jednostek podczas używania deprecation by date w dokumencie API, aby wskazać, kiedy coś zostanie usunięte. Najlepiej użyć schematu rejestracji z adresem e-mail użytkowników klucza API, dzięki czemu można powiadomić ich o dezaktualizacji w określonym zakresie (a la Facebook).W związku z tym nie sądzę, aby trzeba określić wersję gdziekolwiek.