11

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?

user2436721
  • 111
  • 1
  • 4

2 Answers2

5

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

Community
  • 1
  • 1
JP. Aulet
  • 4,375
  • 4
  • 26
  • 39
1

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"
Yogurt
  • 2,913
  • 2
  • 32
  • 63
Sergey Nemchinov
  • 1,348
  • 15
  • 21
  • There is as well a version of the draft marked with "latest", https://greenbytes.de/tech/webdav/draft-ietf-httpapi-deprecation-header-latest.html#syntax In this version the value "true" is not present anymore. – MichaelCkr Oct 19 '22 at 19:31