Undeprecate APIv2 in docs #7579
Conversation
APIv2 is still available, we still use it for application operations, and APIv3 is not quite ready as a replacement for a lot of applications. I think the docs should reflect that, even if we want new users using APIv3.
docs/api/v2.rst
Outdated
| the Docs, you should try to use :doc:`API v3 </api/v3>` instead. API v2 is | ||
| still used by some application operations still. |
There was a problem hiding this comment.
I think we should strongly not recommend the usage of APIv2: "you should try" doesn't sound too strong to me
I'd say something like "we don't recommend the usage of APIv2 because we will remove it soon without notification. You should use APIv3 and if there is something that you can't do with APIv3, please contact us"
I don't want new users using APIv2 to do things that are supported on APIv3 and I want users that are forced to use APIv2 to contact us and let us know what's the use case.
There was a problem hiding this comment.
Yeah, a more aggressive stance would be fine here. I just have an issue calling it deprecated.
We need to go through a formal deprecation process with APIv2 still. Right now, it's in a limbo where it says it's deprecated, but it's still fully functional, and APIv3 is not yet a full replacement for APIv2. When APIv3 is ready to be our primary API, then we can call it deprecated, go through a formal process of alerting users and doing rolling brown outs of APIv2, and finally call it deprecated. Right now, we're sending mixed messages and I was a bit confused by this.
There was a problem hiding this comment.
Added firmer language in e776174
|
Great, and I definitely want to keep up pressure to move to APIv3, but understand it's been hard to get everything through review. Soon! |
APIv2 is still available, we still use it for application operations,
and APIv3 is not quite ready as a replacement for a lot of applications.
I think the docs should reflect that, even if we want new users using
APIv3.