问题
I'm upgrading our REST API endpoints and I want to notify clients when they are calling the to-be-deprecated endpoint.
What header should I use in the response with a message along the lines of "This API version is being deprecated, please consult the latest documentation to update your endpoints"
回答1:
I would not change anything in the status code to be backward compatible. I would add a "Warning" header in the response :
Warning: 299 - "Deprecated API"
You can also specify the "-" with the "Agent" that emits the warning, and be more explicit in the warn-text :
Warning: 299 api.blazingFrog.com "Deprecated API : use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02"
Warning header are specified here : https://tools.ietf.org/html/rfc7234#section-5.5. Warn-code 299 is generic, "Deprecated" is not standard.
You have to tell your API clients to log the HTTP warnings and monitor it.
I've never used it until now, but when my company will be more mature in Rest API I will integrate it.
Edit (2019-04-25) : As @Harry Wood mentioned it, the Warning header is in a chapter related to caching in documentation. The RFC is not clear because it is written that with warn-code 199
The warning text can include arbitrary information to be presented to a human user or logged.This draft https://tools.ietf.org/html/draft-dalal-deprecation-header-00 suggests a new header "Deprecation" which can become a good alternative.
回答2:
You could use 410 (Gone).
Here's how W3C's Status Code Definitions describe it:
410 (Gone)
The requested resource is no longer available at the server and no forwarding address is known. This condition is expected to be considered permanent. Clients with link editing capabilities SHOULD delete references to the Request-URI after user approval. If the server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) SHOULD be used instead. This response is cacheable unless indicated otherwise.
The 410 response is primarily intended to assist the task of web maintenance by notifying the recipient that the resource is intentionally unavailable and that the server owners desire that remote links to that resource be removed. Such an event is common for limited-time, promotional services and for resources belonging to individuals no longer working at the server's site. It is not necessary to mark all permanently unavailable resources as "gone" or to keep the mark for any length of time -- that is left to the discretion of the server owner.
回答3:
I would/ have gone with 301 (Moved Permanently) The 300 series codes are supposed to tell the client they have an action to do.
回答4:
I'd recommend a 207 Multi-Status response, indicating that it's a successful response, but it also potentially has a second deprecated status.
回答5:
There is an HTTP header field called Sunset which is intended to signal an upcoming deprecation of a resource. https://tools.ietf.org/html/draft-wilde-sunset-header is in the last stages of becoming an RFC. Ideally, your API should document that it is going to use Sunset, so that clients can look for it and act upon it, if they want to.
回答6:
Refining @dret's response. There are two relevant HTTP headers for deprecation: Deprecation (https://tools.ietf.org/html/draft-dalal-deprecation-header-00) and Sunset.
To inform users about the planned deprecation, the Deprecation HTTP header should be used. This indicates that the endpoint will be dropped some time in the future. It also allows you to indicate the date when this was announced, and to describe alternate resources.
To inform users about the planned sunset date of the deprecated resource, the Sunset header should be used in addition to the Deprecation header. This is described in section #5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5.
Draft #11 https://tools.ietf.org/html/draft-wilde-sunset-header-11 of the Sunset header clarifies this aspect as well in section 1.4 https://tools.ietf.org/html/draft-wilde-sunset-header-11#section-1.4.
来源：https://stackoverflow.com/questions/13884141/convention-for-http-response-header-to-notify-clients-of-deprecated-api