Advertise deprecated endpoints via Deprecation headers ( draft-ietf-httpapi-deprecation-header-03 )

[ThisIsMissEm]

Pitch

Currently notices of deprecated endpoints are exclusively listed in that endpoints' documentation Version History. This means that people may not notice that they are using deprecated endpoints, and API Clients can't automatically warn when a deprecated API is used.

I'd like to propose that we adopt draft-ietf-httpapi-deprecation-header-03, and advertise as follows:

Deprecation: @1688169599
Link: <https://docs.joinmastodon.org/api/deprecations#<id>; rel="deprecation"; type="text/html"

Where 1688169599 is when the endpoint was or will be deprecated at, in seconds; and <id> is a unique identified for that deprecation on the deprecation pages.

We may also have use in the Sunset HTTP Header, however, this would require fairly exact release dates, which we don't currently have, or we use the sunset rel in a Link header, to indicate upcoming removal of an API. (but I'm not sure if we've ever completely removed an API, a breaking change.

There is a ticket on the documentation repository which is complementary to this.

Motivation

This will help developers be better able to discover when they're using outdated API endpoints, and help them upgrade, ensuring a healthier API community usage.

[LucasGGamerM]

I am in favor of this

[VyrCossont]

Makes sense for client library developers and bot operators, who would be in a position to see error messages if their client library was aware of these headers. I assume this isn't meant to be surfaced to end users.

[ThisIsMissEm]

I assume this isn't meant to be surfaced to end users.

@VyrCossont correct! Though, if you're a developer using a client library, then the client library may choose to expose this information to you via logging.