Convention for HTTP response header to notify clients of deprecated API

rest http http-status-codes deprecation-warning
BlazingFrog picture BlazingFrog · Dec 14, 2012 · Viewed 30.7k times · Source

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"

Answer

BenC picture BenC · Apr 14, 2015

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 is 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 the documentation. However, the RFC is clear Warnings can be used for other purposes, both cache-related and otherwise.

If you prefer an alternate method, this draft https://tools.ietf.org/html/draft-dalal-deprecation-header-00 suggests a new header "Deprecation".

Related questions

REST HTTP status codes for failed validation or invalid duplicate

I am building an application with a REST-based API and have come to the point where I am specifying status codes for each requests. What status code should i send for requests failing validation or where a request is trying …

Read More
HTTP response code for POST when resource already exists

I'm building a server that allows clients to store objects. Those objects are fully constructed at client side, complete with object IDs that are permanent for the whole lifetime of the object. I have defined the API so that clients …

Read More
HTTP status code for "no data available" from an external datasource

Scenario: A POST request is sent to process an order that will result in data retrieval from an external datasource. There are three possible results: The datasource returned data for the request No data was available for the request (this …

Read More