Comment by throw0101c
20 hours ago
> From an API designer's standpoint (especially if that API has paying customers), Hyrum's Law is something that has to be taken into account.
How good-of-an-idea / best practice is API versioning?
/api/v1/foo
/api/v2/foo
What are the pluses and minuses?
A couple of considerations are:
- You have to decide whether to bump the entire API version or only the /foo endpoint. The former can be a big deal (and you don't want to do it often), the latter is messy. Especially if you end up with some endpoints on /v1 (you got it right first time) while others are on /v4 or /v5. Some clients like to hard-code the URL prefix of your API, including the version, as a constant.
- You still have to decide what your deprecation and removal policy will be. Does there come a time when you remove /api/v1/foo completely, breaking even the clients who are using it correctly, or will you support it forever?
It's not easy at all, especially if you have to comply with a backwards compatibility policy. I've had many debates about whether it's OK to introduce breaking changes if we consider them to be bug fixes. It depends on factors like whether either behaviour is documented and subjective calls on how "obviously unintended" the behaviour might be.
Plus, easy to see that you might have to do something different to move over to v2 as client.
Minus, You will support v1 forever. It's almost impossible to make it go away.
you end up with a lot of versions if you version everything that could change some non-guaranteed behavior in some corner case.