Wersjonowanie interfejsów API REST. Każdy interfejs API ma własną wersję

15

Bardzo często określa się wersje interfejsów API REST w adresie URL, szczególnie na początku ścieżki, tj. Coś w stylu:

POST /api/v1/accounts
GET /api/v1/accounts/details

Jednak nie widziałem żadnego projektu, w którym wersja jest powiązana z każdym interfejsem API. Innymi słowy, utrzymujemy wersję każdego interfejsu API osobno. to znaczy:

POST /api/accounts/v2
GET /api/accounts/details/v3

Korzystając z tego podejścia, zwiększamy wersję API konkretnego API, gdy potrzebna jest zmiana podziału, nie ma potrzeby zwiększania wersji całych API.

Jakie są wady używania tego stylu zamiast wspólnego?

Eng.Fouad
źródło

Odpowiedzi:

13

To, co nazywacie pojedynczymi interfejsami API REST, może być nazywane szczególnym zestawem zasobów lub zasobów interfejsu API REST . Można również spojrzeć na to jako na funkcje interfejsu API REST . Tak jak w przypadku każdego oprogramowania, cały pakiet jest wersjonowany / aktualizowany, a nie pojedyncze funkcje lub zasoby.

Twoje pytanie miałoby sens w kontekście, w którym zasoby pakietu API REST są modułowe, a więc potencjalnie opracowane i wersjonowane osobno.

Następnie, o ile widzę, główne wady proponowanej konwencji nazewnictwa lokalizatora zasobów to:

  • Dla użytkownika interfejsu API spowodowałoby to znacznie bardziej złożone lokalizatory zasobów, mniej przewidywalne, mniej zapadające w pamięć i mniej stabilne.
  • Dla modułu wywoływacza (S) , to teraz więcej pracy, aby mieć do czynienia z tym wersjonowania w ich własnym lokalizator zasobów.
  • Zmiany w lokalizatorach zasobów stają się znacznie częstsze, ponieważ aktualizuje się wiele modułów, więc powyższe minusy są wykładnicze ...

Podczas tworzenia interfejsu API jednym z głównych celów jest ułatwienie korzystania z ...

Możesz znaleźć lepszy sposób na wprowadzenie przełomowej zmiany, a nawet wersjonowanie interfejsu API REST za pomocą nagłówka HTTP?

Aby dowiedzieć się więcej o podejściu do nagłówków HTTP, zobacz inne odpowiedzi poniżej i: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

ClemC
źródło
12

Oto jeszcze lepsze podejście: użyj negocjacji treści, aby zaktualizować interfejs API za pomocą nagłówków Content-Typei Accept:

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

Aby uzyskać inną wersję, poproś o nią z innym typem treści w Accept. W ten sposób poszczególne wersje obsługiwane przez serwer są całkowicie niezależne od struktury adresu URL. Ten sam serwer może obsługiwać wiele wersji, wybierając po prostu odpowiedź, na podstawie Acceptnagłówka. Alternatywnie, jeśli chcesz trzymać się różnych wdrożeń dla różnych wersji, możesz umieścić serwer proxy przed różnymi wersjami usługi, które wybrały, do którego z nich należy przesyłać żądania na podstawie Acceptnagłówka.

Pozwala to również obsługiwać nowe formaty o różnej semantyce (nie tylko różne wersje) na tych samych punktach końcowych. Na przykład, wysłanie listy kont do POST /api/accountsmoże oznaczać utworzenie partii i nie trzeba będzie budować dla niej osobnego punktu końcowego interfejsu API.

Jacek
źródło
omg nagłówek accept musi być najgorszym wyborem sygnalizacji wersji. użyj nagłówka wersji, jeśli możesz, ścieżki URL, jeśli musisz (tj. routing AWS)
Ewan
@Ewan Dlaczego? Nagłówek wersji niestandardowej sugeruje, że różne wersje są tym samym zasobem bez informowania pośredników, że treść może być inna. Buforowy serwer proxy nie wiedziałby, jak używać nagłówka, aby nie obsługiwać odpowiedzi buforowanych v1 na żądania v2.
Jack
użyj nagłówka odpowiedzi var, jeśli jeszcze nie używasz no-cache dla żądań interfejsu API! typ zawartości ma już znaczenie, podświadczenie o nim do prywatnego użytku utrudnia życie konsumentom
Ewan
@Ewan Do tego służy vndczęść i +składnia typu: wskazanie, że jest to podtyp application/jsontypu specyficzny dla dostawcy . Właśnie do tego są przeznaczone typy treści. Twój zasób jest dostępny w wielu formatach. Pytasz klienta, jaki format wybrać. Ponadto nie ma powodu, dla którego żądania API nie mogą używać standardowej semantyki buforowania HTTP.
Jack
jeśli naprawisz błąd w myapi v2, nie zwrócisz nowego typu MIME.
Ewan
5

Kluczową sprawą jest to, że jeśli wersja każdego punktu końcowego jest tworzona osobno, musisz mieć możliwość wdrożenia każdego punktu końcowego osobno.

Interfejsy API mają zwykle jedną wersję, ponieważ wszystkie punkty końcowe znajdują się w tej samej bazie kodu, a zatem mają wspólne zależności i są wdrażane razem.

Jeśli nie aktualizujesz wersji, gdy wprowadzasz zmiany, ponieważ „Och, jestem pewien, że moja zmiana nie ma na to wpływu”, możesz mieć kłopoty, gdy popełnisz błąd.

Ponadto konieczne będzie jednoczesne wdrożenie zarówno wersji 1, jak i 2 interfejsu API. Zwykle odbywa się to poprzez wdrożenie każdej wersji na osobnym serwerze i odpowiednie kierowanie ruchu.

Jeśli nie masz jednej wersji interfejsu API, staje się to znacznie bardziej złożone.

Ewan
źródło