Per feedback from @ethanresnick (Support for deprecation), this is a quick proposal for api deprecations. It was written quickly on a Friday evening so there is much room for improvement.
Hopefully this can start a productive discussion! https://gist.github.com/iamvery/c65ae9eb2a88a52f21a1
I’d love to get the ball rolling on this again, I think there’s a lot of benefit to come from a standard way of expressing deprecations in the API. For example, a generic json:api client could automatically report such deprecation warnings, making it more likely that API clients would be able to handle it.
Anyways, I think we would need the ability to express more complex deprecations than just standard renames. Would be good to offer warnings of removal-without-replacement and things such as splitting an attribute/association (for example, at kitsu.io, we recently replaced a single polymorphic association with multiple monomorphic associations) or changing format of an attribute.
Completely missed this threadzurrection but followed, read and responded anyway. At this time my current belief is json-api is not the correct abstraction to resolve this issue, but I do agree it is something which should be handled to drive hypermedia api adoption forward.