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

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?

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/

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.

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.