108

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"

Christophe Roussy
  • 16,299
  • 4
  • 85
  • 85
BlazingFrog
  • 2,265
  • 3
  • 21
  • 31

6 Answers6

86

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://www.rfc-editor.org/rfc/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://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00 suggests a new header "Deprecation".

Edit (2021-01-04) : As @Dima Parzhitsky mentioned it, MDN says this header is deprecated

BenC
  • 1,647
  • 18
  • 25
  • 1
    The warn-date at the end of the warning-value serves no purpose here, and it’s best to omit it, or you risk confusing clients: “If a recipient . . . receives a warn-date that is different from the `Date` value in the same message, the recipient MUST exclude the warning-value . . . before . . . using the message.” – Vasiliy Faronov May 27 '16 at 15:48
  • If you do include the warn-date, it must be formatted in the same way as the `Date` header: `"Thu, 02 Apr 2015 12:25:32 GMT"`. – Vasiliy Faronov May 27 '16 at 15:51
  • @VasiliyFaronov : you're right, because in that case (deprecated API) this warning message will always be true in the future. So if the response (with the warning message) is sent by a cache in a proxy and that the message date is different, the warning will be ignored whereas it will still be valid. I edit the response – BenC Mar 06 '17 at 14:28
  • Isn't that "warning" header related to caching though? I mean in your documentation link it mentions caching, but also that whole RFC document seems to be caching related. But the `Warning` header does look good as free-text place to describe the deprecation. The `Deprecation` and `Sunset` headers mentioned in other answers, would seem to be an emerging standard solution for describing the deprecation in a tighter more potentially machine-readable way. – Harry Wood Apr 17 '19 at 08:53
  • You're right @HarryWood, I did not see that. The main chapter is titled "This section defines the syntax and semantics of HTTP/1.1 header fields related to caching." However, it is the only standard today. You mentioned https://tools.ietf.org/html/draft-dalal-deprecation-header-00 which should be used instead. I edit the post. – BenC Apr 25 '19 at 09:11
  • 1
    `Warning` header is not related to caches only. The first sentence in the `Warning` section is "Warnings can be used for other purposes, both cache-related and otherwise." – Çelebi Murat Feb 27 '20 at 12:53
  • 5
    Note that HTTP Warnings themselves [are getting deprecated](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Warning) now – Parzh from Ukraine Apr 29 '21 at 09:53
51

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.

Emanuil Rusev
  • 34,563
  • 55
  • 137
  • 201
  • 52
    The problem with 410 is that it does not match the "to-be-deprecated" requirement... It works fine when the API is gone, but not that it *will* be gone in the *future*. – Julien Genestoux Sep 12 '14 at 13:06
  • 4
    If you return 410 you will break your backward compatibility – BenC Jan 22 '16 at 14:52
  • 6
    `410 Gone` it's not about deprecation, it's much about method available no more. As @BenC said, the better way is to use [Warning header](https://tools.ietf.org/html/rfc7234#section-5.5) – sempasha May 19 '16 at 14:37
  • 3
    This could be the next phase of the deprecated API – Shiplu Mokaddim Nov 05 '18 at 08:52
17

I would/ have gone with 301 (Moved Permanently) The 300 series codes are supposed to tell the client they have an action to do.

Community
  • 1
  • 1
u07ch
  • 13,324
  • 5
  • 42
  • 48
  • 7
    That's probably what I'll use once the endpoint is actually removed but I want to give them a chance to be notified for some time (assuming they will be looking at the HTTP headers in the response) so that they can make the necessary changes on their end. – BlazingFrog Dec 14 '12 at 18:25
  • 2
    There isnt really a status for going to move. 302 ( The requested resource resides temporarily in another location, but it can still be found at the requested URI.) ... – u07ch Dec 14 '12 at 19:37
  • 2
    I'm not looking for a status but for a "standard" header to add to the response. – BlazingFrog Dec 14 '12 at 21:54
  • 1
    There's no standard header for this kind of response. You should create a header of your own and describe it in your own api's documentation. – Brian Kelly Dec 15 '12 at 04:37
  • 1
    I think any response code >= 300 is supposed to break things. 299 will allow clients to keep their application alive until the API is disabled while they make the necessary changes. – devlord Apr 11 '16 at 20:02
  • 1
    Status code is part of your REST API. Since API is agreement between client and service, so first of all you should warn clients about future breaking changes. Some clients may not support redirections, so after getting `301 Moved Permanently` they will assume request is failed due to unknown response code (they expects `200 Success` for example). Other words - you risk to break compatibility with clients by changing status code of response. As @BenC said, the better way is to use [Warning header](https://tools.ietf.org/html/rfc7234#section-5.5) to notify clients. – sempasha May 19 '16 at 14:53
  • That "warning" header seems to be caching related.The `Deprecation` and `Sunset` headers mentioned in other answers, would seem to be an emerging standard solution to this problem. – Harry Wood Apr 16 '19 at 16:10
13

Refining @dret's response. There are two relevant HTTP headers for deprecation: Deprecation (https://datatracker.ietf.org/doc/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://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00#section-5.

Draft #11 https://datatracker.ietf.org/doc/html/draft-wilde-sunset-header-11 of the Sunset header clarifies this aspect as well in section 1.4 https://datatracker.ietf.org/doc/html/draft-wilde-sunset-header-11#section-1.4.

Community
  • 1
  • 1
sdatspun2
  • 131
  • 1
  • 2
7

I'd recommend a 207 Multi-Status response, indicating that it's a successful response, but it also potentially has a second deprecated status.

typeoneerror
  • 55,990
  • 32
  • 132
  • 223
  • 2
    Interesting. I didn't know about that one, but I think in practice there's a strong danger you'll be introducing a breaking change for _some_ clients by swapping to a different response code even if it's still in the 200 range. I guess you might do a sort of gentle ratcheting up of the pressure. Start with a `Deprecation` header (which clients are likely to ignore unfortunately) then later use this 207 code, then later 301 moved, then finally 410 gone! – Harry Wood Apr 16 '19 at 16:18
7

There is an HTTP header field called Sunset which is intended to signal an upcoming deprecation of a resource. https://datatracker.ietf.org/doc/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.

Community
  • 1
  • 1
dret
  • 531
  • 3
  • 7