Tôi đang nâng cấp các điểm cuối API REST của mình và tôi muốn thông báo cho khách hàng khi họ đang gọi điểm cuối không dùng nữa.
Tôi nên sử dụng tiêu đề nào trong phản hồi có thông báo dọc theo dòng "Phiên bản API này không được dùng nữa, vui lòng tham khảo tài liệu mới nhất để cập nhật điểm cuối của bạn"
Câu trả lời:
Tôi sẽ không thay đổi bất kỳ điều gì trong mã trạng thái để tương thích ngược. Tôi sẽ thêm tiêu đề "Cảnh báo" trong phản hồi:
Warning: 299 - "Deprecated API"
Bạn cũng có thể chỉ định "-" với "Tác nhân" phát ra cảnh báo và rõ ràng hơn trong văn bản cảnh báo:
Warning: 299 api.blazingFrog.com "Deprecated API: use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02"
Tiêu đề cảnh báo được chỉ định tại đây: https://tools.ietf.org/html/rfc7234#section-5.5 . Mã cảnh báo 299 là chung chung, "Không được chấp nhận" không phải là tiêu chuẩn.
Bạn phải yêu cầu khách hàng API của mình ghi lại các cảnh báo HTTP và giám sát nó.
Tôi chưa bao giờ sử dụng nó cho đến bây giờ, nhưng khi công ty của tôi trưởng thành hơn trong Rest API, tôi sẽ tích hợp nó.
Chỉnh sửa (2019-04-25): Như @Harry Wood đã đề cập, tiêu đề Cảnh báo nằm trong chương liên quan đến bộ nhớ đệm trong tài liệu. Tuy nhiên, RFC rõ ràng
Warnings can be used for other purposes, both cache-related and otherwise.Nếu bạn thích một phương pháp thay thế, bản nháp này https://tools.ietf.org/html/draft-dalal-deprecation-header-00 đề xuất một tiêu đề mới "Không dùng nữa".
Datetiêu đề: "Thu, 02 Apr 2015 12:25:32 GMT".
Warningtiêu đề có vẻ tốt là nơi có văn bản tự do để mô tả việc không dùng nữa. Các tiêu đề Deprecationvà Sunsettiêu đề được đề cập trong các câu trả lời khác, dường như sẽ là một giải pháp tiêu chuẩn mới nổi để mô tả việc ngừng sử dụng theo cách chặt chẽ hơn có khả năng đọc được bằng máy.
Warningtiêu đề không chỉ liên quan đến bộ nhớ đệm. Câu đầu tiên trong Warningphần là "Cảnh báo có thể được sử dụng cho các mục đích khác, cả liên quan đến bộ nhớ cache và các mặt khác."
Bạn có thể sử dụng 410 (Gone) .
Đây là cách Định nghĩa mã trạng thái của W3C mô tả nó:
410 (Đã qua)
Tài nguyên được yêu cầu không còn khả dụng tại máy chủ và không xác định được địa chỉ chuyển tiếp. Tình trạng này dự kiến sẽ được coi là vĩnh viễn. Khách hàng có khả năng chỉnh sửa liên kết NÊN xóa các tham chiếu đến URI Yêu cầu sau khi người dùng chấp thuận. Nếu máy chủ không biết, hoặc không có cơ sở để xác định, liệu tình trạng này có vĩnh viễn hay không, thì mã trạng thái 404 (Không tìm thấy) NÊN được sử dụng thay thế. Phản hồi này có thể lưu vào bộ nhớ cache trừ khi được chỉ định khác.
Phản hồi 410 chủ yếu nhằm hỗ trợ nhiệm vụ bảo trì web bằng cách thông báo cho người nhận rằng tài nguyên cố ý không khả dụng và chủ sở hữu máy chủ muốn xóa các liên kết từ xa tới tài nguyên đó. Sự kiện như vậy thường xảy ra đối với các dịch vụ khuyến mại, có thời hạn và các tài nguyên thuộc về các cá nhân không còn làm việc tại trang web của máy chủ. Không cần thiết phải đánh dấu tất cả các tài nguyên vĩnh viễn không khả dụng là "đã biến mất" hoặc giữ dấu trong bất kỳ khoảng thời gian nào - đó là quyết định của chủ sở hữu máy chủ.
410 Gonenó không phải là về việc không dùng nữa, mà là về phương pháp không còn nữa. Như @BenC đã nói, cách tốt hơn là sử dụng tiêu đề Cảnh báo
Tôi sẽ / đã đi với 301 (Đã di chuyển vĩnh viễn) Mã sê-ri 300 được cho là để cho khách hàng biết họ có hành động phải làm.
Tôi muốn đề xuất một 207 Multi-Statusphản hồi, cho biết rằng đó là một phản hồi thành công, nhưng nó cũng có khả năng có trạng thái thứ hai không được dùng nữa.
Deprecationtiêu đề (mà khách hàng có khả năng bỏ qua không may) sau đó sử dụng mã 207 này, sau đó 301 chuyển đến, rồi cuối cùng là 410 biến mất!
Đang tinh chỉnh phản hồi của @ dret. Có hai tiêu đề HTTP có liên quan không được dùng nữa:Deprecation ( https://tools.ietf.org/html/draft-dalal-deprecation-header-00 ) và Sunset.
Để thông báo cho người dùng về kế hoạch ngừng sử dụng, Deprecation tiêu đề HTTP nên được sử dụng. Điều này cho thấy rằng các thiết bị đầu cuối sẽ bị bỏ một chút thời gian trong tương lai. Nó cũng cho phép bạn chỉ ra ngày thông báo điều này và mô tả các tài nguyên thay thế.
Để thông báo cho người dùng về ngày ngừng hoạt động dự kiến của tài nguyên không dùng nữa, Sunset tiêu đề này nên được sử dụng ngoài tiêu đề Không dùng nữa. Điều này được mô tả trong phần # 5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5 .
Bản nháp # 11 https://tools.ietf.org/html/draft-wilde-sunset-header-11 của Sunsettiêu đề làm rõ khía cạnh này cũng như trong phần 1.4 https://tools.ietf.org/html/draft-wilde -sunset-header-11 # section-1.4 .
Có một trường tiêu đề HTTP được gọi Sunsetnhằm mục đích báo hiệu sắp ngừng sử dụng tài nguyên. https://tools.ietf.org/html/draft-wilde-sunset-header đang trong giai đoạn cuối để trở thành RFC. Lý tưởng nhất, API của bạn nên ghi lại rằng nó sẽ sử dụng Sunset, để khách hàng có thể tìm kiếm nó và hành động theo nó, nếu họ muốn.
Dategiá trị trong cùng một thông báo, người nhận PHẢI loại trừ giá trị cảnh báo. . . trước . . . bằng cách sử dụng tin nhắn. ”