Phiên bản API REST. Mỗi API có phiên bản riêng

Rất phổ biến để chỉ định phiên bản API REST trong URL, cụ thể là ở đầu đường dẫn, nghĩa là:

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

Tuy nhiên, tôi chưa thấy bất kỳ thiết kế nào mà phiên bản được liên kết với từng API. Nói cách khác, chúng tôi duy trì phiên bản của từng API riêng biệt. I E:

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

Sử dụng phương pháp này, chúng tôi tăng phiên bản API của API cụ thể khi cần thay đổi, không cần tăng phiên bản của toàn bộ API.

Hạn chế của việc sử dụng phong cách này thay vì phong cách phổ biến là gì?

Những gì bạn gọi là các API REST đơn lẻ có thể được gọi là bộ tài nguyên hoặc tài nguyên cụ thể của API REST . Bạn cũng có thể xem nó như các chức năng của API REST . Chẳng hạn như bất kỳ loại phần mềm nào, toàn bộ gói được phiên bản / cập nhật, không phải là các chức năng hoặc tài nguyên đơn lẻ.

Câu hỏi của bạn sẽ có ý nghĩa trong bối cảnh nơi tài nguyên của gói REST API được mô đun hóa và do đó có khả năng được phát triển và phiên bản riêng biệt.

Sau đó, theo như tôi thấy, nhược điểm chính của quy ước đặt tên tài nguyên được đề xuất của bạn là:

• Đối với người dùng API , nó sẽ dẫn đến các bộ định vị tài nguyên phức tạp hơn nhiều, ít dự đoán hơn, ít đáng nhớ hơn và kém ổn định hơn.
• Đối với (các) nhà phát triển mô-đun , giờ đây phải làm việc nhiều hơn để xử lý phiên bản này trong trình định vị tài nguyên của riêng họ .
• Những thay đổi trong bộ định vị tài nguyên trở nên thường xuyên hơn, cũng như có nhiều mô-đun đang cập nhật nên những nhược điểm ở trên là theo cấp số nhân ...

Khi xây dựng API, một trong những mục tiêu chính của bạn là làm cho nó dễ sử dụng ...

Bạn có thể tìm thấy một cách tốt hơn để giới thiệu một thay đổi đột phá hoặc thậm chí là phiên bản API REST có thể có tiêu đề HTTP?

Để biết thêm một chút về cách tiếp cận tiêu đề HTTP, hãy xem các câu trả lời khác bên dưới và: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

Đây là một cách tiếp cận thậm chí tốt hơn: sử dụng đàm phán nội dung để phiên bản API của bạn với các tiêu đề Content-Typevà 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 ... }

Để có được một phiên bản khác, chỉ cần yêu cầu nó với một loại nội dung khác Accept. Theo cách này, các phiên bản cụ thể mà máy chủ của bạn hỗ trợ hoàn toàn độc lập với cấu trúc URL của bạn. Cùng một máy chủ có thể hỗ trợ nhiều phiên bản chỉ bằng cách chọn phản hồi dựa trên Accepttiêu đề. Ngoài ra, nếu bạn muốn gắn bó với các triển khai khác nhau cho các phiên bản khác nhau, bạn có thể đặt proxy trước các phiên bản dịch vụ khác nhau đã chọn phiên bản nào để chuyển tiếp yêu cầu dựa trên Accepttiêu đề.

Điều này cũng cho phép bạn hỗ trợ các định dạng mới với các ngữ nghĩa khác nhau (không chỉ các phiên bản khác nhau) trên cùng một điểm cuối. Chẳng hạn, POST một danh sách các tài khoản /api/accountscó thể có nghĩa là tạo hàng loạt và bạn sẽ không cần phải xây dựng một điểm cuối API riêng cho nó.

Điều quan trọng là nếu bạn phiên bản riêng từng điểm cuối thì bạn phải có thể triển khai riêng từng điểm cuối.

API thường có một phiên bản vì tất cả các điểm cuối đều nằm trong cùng một cơ sở mã và do đó có các phụ thuộc được chia sẻ và được triển khai cùng nhau.

Nếu bạn không cập nhật phiên bản khi bạn thực hiện thay đổi vì "Ồ tôi chắc chắn rằng thay đổi của tôi không ảnh hưởng đến điều đó", bạn sẽ gặp rắc rối khi mắc lỗi.

Ngoài ra, bạn sẽ muốn triển khai cả v1 và v2 API của mình cùng một lúc. Điều này thường được thực hiện bằng cách triển khai mỗi phiên bản đến một máy chủ riêng biệt và định tuyến lưu lượng phù hợp.

Nếu bạn không có phiên bản API đơn thì điều này trở nên phức tạp hơn nhiều.