I would think if they payload changes in some manner that could be a breaking change as well right? Not sure if this fits in one of the two categories you mentioned.
I'll say this.. I don't know if the way I do things is not a common practice, but I typically avoid versioning and breaking changes by introducing a new endpoint instead. In this way, the existing API continues to work as it has, documentation stays in sync, but the added endpoint is now in place to allow a period of time for migration. Documentation for that endpoint stays in sync and so on. It could be as simple/silly as POST /auth, POST /auth2, POST /auth3, etc. But the point is, it avoids a lot of the headaches you mention here. It gives the opportunity for the API product team to inform their API customers of the new endpoint, a deprecation time on the original, and some migration details making it seamless when customers are ready. At that point, the old endpoint returns a 302 with the new endpoint, so that any customers that didn't listen/update, will suddenly get a 302 and will "wake up" as to what happened. Ideally nobody runs in to that.
I would think if they payload changes in some manner that could be a breaking change as well right? Not sure if this fits in one of the two categories you mentioned.
I'll say this.. I don't know if the way I do things is not a common practice, but I typically avoid versioning and breaking changes by introducing a new endpoint instead. In this way, the existing API continues to work as it has, documentation stays in sync, but the added endpoint is now in place to allow a period of time for migration. Documentation for that endpoint stays in sync and so on. It could be as simple/silly as POST /auth, POST /auth2, POST /auth3, etc. But the point is, it avoids a lot of the headaches you mention here. It gives the opportunity for the API product team to inform their API customers of the new endpoint, a deprecation time on the original, and some migration details making it seamless when customers are ready. At that point, the old endpoint returns a 302 with the new endpoint, so that any customers that didn't listen/update, will suddenly get a 302 and will "wake up" as to what happened. Ideally nobody runs in to that.
Just my thoughts on the matter.