Convention for HTTP response header to notify legacy API clients

Question

I am updating our REST API endpoints and I want to notify clients when they call an outdated endpoint. Which header should be used in the response with the message in the line "This version of the API is out of date, refer to the latest documentation for updating endpoints"

Answer 1

I would not change anything in the status code to be backward compatible. I would add a “Warning” heading in the response:

Warning: 299 - "Deprecated API" 

You can also specify a “-” with the “Agent” that issues the warning, and be more explicit in the warning text:

 Warning: 299 api.blazingFrog.com "Deprecated API : use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02" 

A warning header is listed here: https://tools.ietf.org/html/rfc7234#section-5.5 . Warning code 299 is general; Obsolete is not standard.

You need to tell your clients APIs to log HTTP alerts and track them.

I have never used it so far, but when my company becomes more mature in the Rest API, I integrate it.

Answer 2

You can use 410 (gone) .

Here's how the W3C Status Code Definitions describe it:

410 (left)

The requested resource is no longer available on the server, and no forwarding address is known. This condition is expected to be considered permanent. Clients with link editing capabilities SHOULD remove the Request-URI links after user approval. If the server does not know or is unable to determine whether the condition is constant, the 404 status code (not found) MUST be used instead. This response can be cached unless otherwise indicated.

Answer 410 is primarily intended to help with notifying the recipient that the resource is intentionally unavailable and that server owners wish that deleted links to this resource are deleted. Such an event is common for a limited time, advertising services and resources owned by people no longer work on the server. It is not necessary to mark all permanently inaccessible resources as "gone" or to save a tag for any period of time - this remains at the discretion of the server owner.

Answer 3

I would go with 301 (moved constantly). 300 series codes should inform the client that they have an action.

Answer 4

I would recommend a 207 Multi-Status response indicating that this is a successful response, but it also potentially has a second outdated status.

Answer 5

There is an HTTP header field called Sunset that is intended to alert you that a resource is about to become obsolete. https://tools.ietf.org/html/draft-wilde-sunset-header is in the final stages of becoming an RFC. Ideally, your API should document that it will use Sunset so that customers can search for it and act if they want.

Answer 6

Refining @dret 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 of planned obsolescence, the Deprecation HTTP header should be used. This indicates that the endpoint will be deleted in the future. It also allows you to specify the date when it was announced, and describe alternative resources.

To inform users of the planned closing date for an obsolete resource, the Sunset header should be used in addition to the Deprecation header. This is described in section No. 5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5 .

Draft No. 11 of the https://tools.ietf.org/html/draft-wilde-sunset-header-11 of the Sunset heading clarifies this aspect in section 1.4 https://tools.ietf.org/html/draft- wilde-sunset- header-11 # section-1.4 .