Mã trạng thái HTTP chính xác cho: Phiên bản API này đã bị ngừng sử dụng là gì?

Tôi có API RESTful. Có 3 phiên bản của nó: v1, v2 và v3. Tôi sắp xuất bản v4 và chúng tôi đã quyết định ngừng v1, nghĩa là tất cả các yêu cầu http://example.com/v1/resourcesẽ không thành công, nhưng các cuộc gọi đến http://example.com/v2/resourcesẽ tiếp tục hoạt động.

Cách thích hợp để chỉ ra thất bại là gì? Tôi đã xem xét sử dụng 410 GONEmã trạng thái, nhưng điều đó chỉ ra rằng tài nguyên không còn nữa. Tuy nhiên, tài nguyên có khả năng IS vẫn có sẵn, chỉ có nó phải được yêu cầu theo một cách khác.

Tôi cũng đã xem xét một 400mã trạng thái chung , nhưng điều đó cũng có vẻ kỳ lạ. Có một câu trả lời tiêu chuẩn cho điều này?

Dường như không có một tiêu chuẩn.

Câu trả lời của StackOverflow nghiêng về 410 Gone, nhưng tôi nghĩ 301 MOVED PERMANENTLY là phù hợp hơn.

Để đưa ra lựa chọn chính xác, chúng tôi phải xem xét trường hợp cụ thể của bạn. Nếu mục tiêu của bạn là khiến tất cả các cuộc gọi được thực hiện cho API v1 không thành công mà không thực hiện thêm bất kỳ hành động nào, 410 Gone sẽ hoạt động cho điều đó. Nếu bạn muốn một số liên tục, chẳng hạn như chuyển hướng ứng dụng khách sang phiên bản API mới hơn, nơi cuộc gọi của họ có thể thành công, 3XX hoạt động, nhưng bạn chọn cái nào? Tôi nghĩ rằng nếu bạn đang cố gắng tắt API v1, 301 MOVED PERMANENTLY giúp chỉ ra rằng tốt hơn so với 303 XEM KHÁC vì 301 cho thấy rằng tất cả các yêu cầu trong tương lai nên được thực hiện cho url mới trong khi 303 không cho biết liệu tình huống này có hay không dài hạn.

Tôi sẽ khuyên bạn nên thiết kế API theo cách sao cho mỗi phiên bản vẫn tương thích ngược, để 301 MOVED PERMANENTLY sẽ giữ cho API của bạn tồn tại và cập nhật bất cứ khi nào bạn thêm điểm cuối mới cho các phiên bản API mới. Tôi nghĩ đó là những gì bạn đang cố gắng làm.

Mã trạng thái HTTP

Mã trạng thái HTTP 302 ban đầu quá rộng và do đó được triển khai / sử dụng không chính xác, do đó, 303 và 307 được tạo ra để phân biệt giữa trường hợp sử dụng kép của 302. Một số API sử dụng 303 cho các mục đích khác.

301 MOVED PERENTENTLY - Mã trạng thái 301 (Đã di chuyển vĩnh viễn) chỉ ra rằng tài nguyên đích đã được gán một URI vĩnh viễn mới và mọi tham chiếu trong tương lai cho tài nguyên này phải sử dụng một trong các URI kèm theo.

302 FOUND - Mã trạng thái 302 (Đã tìm thấy) chỉ ra rằng tài nguyên đích tạm thời nằm trong một URI khác. Do việc chuyển hướng có thể bị thay đổi theo dịp, nên khách hàng phải tiếp tục sử dụng URI yêu cầu hiệu quả cho các yêu cầu trong tương lai.

303 XEM KHÁC - Phản hồi 303 đối với yêu cầu GET cho biết rằng máy chủ gốc không có đại diện cho tài nguyên đích có thể được máy chủ chuyển qua HTTP. Tuy nhiên, giá trị trường Vị trí đề cập đến một tài nguyên mô tả tài nguyên đích, như vậy việc đưa ra yêu cầu truy xuất trên tài nguyên khác đó có thể dẫn đến một đại diện hữu ích cho người nhận mà không ngụ ý rằng nó đại diện cho tài nguyên đích ban đầu.

410 Gone - Mã trạng thái 410 (Đã qua) cho biết rằng quyền truy cập vào tài nguyên đích không còn khả dụng tại máy chủ gốc và điều kiện này có thể là vĩnh viễn. Nếu máy chủ gốc không biết hoặc không có cơ sở để xác định, liệu điều kiện có vĩnh viễn hay không, mã trạng thái 404 (Không tìm thấy) nên được sử dụng thay thế.

Làm thế nào để các API hiện có xử lý việc này?

Có lẽ bạn có thể lấy một trang từ API Youtube của Google :

Khi yêu cầu API không thành công, YouTube sẽ trả về mã phản hồi HTTP 4xx hoặc 5xx xác định chung về lỗi cũng như phản hồi XML cung cấp thông tin cụ thể hơn về (các) lỗi gây ra lỗi. Đối với mỗi lỗi, phản hồi XML bao gồm phần tử miền, phần tử mã và có thể là phần tử vị trí.

• API BigC Commerce sử dụng 302 FOUND.
• Nguyên tắc API API của Atlassian gợi ý ở 301 MOVED PERMANENTLY cùng với một mã phụ mô tả lỗi một cách chi tiết. Điều này tương tự như cách tiếp cận API Youtube.

Đọc thêm:

• API REST được phiên bản như thế nào?
• Thiết kế API Netflix: Khi nào cần Xu hướng

Chuyển hướng là tuyệt vời cho các tài nguyên đã di chuyển. Thay vì chuyển hướng vĩnh viễn 301 (sẽ chỉ ra việc đổi tên mà không thay đổi API), tôi sẽ sử dụng chuyển hướng "Xem khác" 303.

Cần vẫn hỗ trợ di sản mà không chuyển hướng? Ngay cả khi bạn vẫn đang hỗ trợ nó và sâu bên dưới nó vẫn được triển khai, 501 dường như khá thuận tay với tình huống của bạn. Những người biết vẫn có thể sử dụng nó, trong khi các randoms sẽ thấy 501 cho v1.

10.5.2 501 Không được triển khai

Máy chủ không hỗ trợ các chức năng cần thiết để thực hiện yêu cầu. Đây là phản hồi thích hợp khi máy chủ không nhận ra phương thức yêu cầu và không có khả năng hỗ trợ nó cho bất kỳ tài nguyên nào.

http://www.w3.org/Prot Protocol / rfc2616 / rfc2616-sec10.html

Tôi sẽ sử dụng 503 với thông báo rằng dịch vụ không khả dụng và cho biết sẽ sử dụng phiên bản mới hơn. Tin nhắn này có thể được trả lại cho 50% các cuộc gọi và trong thời gian dần dần tăng lên 100%.

Để di chuyển trong suốt, tôi sẽ sử dụng 308 - Chuyển hướng vĩnh viễn, vì phương thức này không sửa đổi động từ (POST sẽ là POST) không giống như 301.