Warning client about deprecated REST API

Question

We are deprecating the REST service and we want to inform the client about this. what is the best practice followed?

I can think of following options

1. Pass the deprecation warning message as part of service response JSON/XML
2. Pass the warning message in HTTP “Warning” Response header.

Could you please share your ideas?

Breakup

Answer 1

I would not change anything in the status code or in the service response to be backward compatible. I would add a "Warning" header in the response.

Warning: 299 - "Deprecated API"

You could also check this (old) response: https://softwareengineering.stackexchange.com/questions/55081/deprecate-a-web-api-best-practices

Guilford

The Warning header is now deprecated. – Advertise

Answer 2

There is an IETF draft "The Deprecation HTTP Header Field" which recommends adding special HTTP-headers to server response.

Examples

The first example shows a deprecation header field without date information:

Deprecation: true

The second example shows a deprecation header with date information and a link to the successor version:

Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version"

The third example shows a deprecation header field with links for the successor version and for the API’s deprecation policy. In addition, it shows the sunset date for the deprecated resource:

Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Sunset: Wed, 11 Nov 2020 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version", <https://developer.example.com/deprecation>; rel="deprecation"

Pallua

There is as well a version of the draft marked with "latest", greenbytes.de/tech/webdav/… In this version the value "true" is not present anymore. – Nicolasanicolau