search

matrix-org / matrix-spec

The Matrix protocol specification
Apache License 2.0
193 stars 96 forks source link

Consider having API deprecation headers on requests #345

Open turt2live opened 6 years ago

turt2live commented 6 years ago

When people are using old endpoints, they may not be aware that the endpoint they are using is N years old. Twitter uses an interesting approach in that they have an x-api-warn and similar headers on requests that clients are expected to log about. Having something similar could make some sense for matrix.

More information about Twitter's approach is here (under "Versioning Strategy"): https://developer.twitter.com/en/docs/ads/general/overview/versions.html

richvdh commented 6 years ago

It's interesting to see that they are using the one-version-for-the-whole-API-surface thing that I have so railed about in our C-S API. I'm still not sure it gives us the flexibility we need to evolve the API quickly.

turt2live commented 6 years ago

It doesn't really help us with making changes faster, but it does help us reach a larger audience when something does need to be deprecated/broken. Chances are people who use ancient clients will not see the tweet, blog post, screaming in rooms, and general chatter about an upcoming deprecation - if we added in-request warnings that clients can advertise to the user, we have a better chance at reaching those people.

Very much a "in 5-10 years when..." thing and less of a rapid evolution thing.

richvdh commented 6 years ago

sorry yes, to be clear my "not sure it gives us the flexibility we need" was related to the shape of their endpoint paths (/1/..., /2/..., etc), and not x-api-warn. I should probably have kept my off-topic ramblings elsewhere.