DEV Community

Discussion on: Best Practices for Versioning REST and GraphQL APIs

Collapse
 
dbanty profile image
Dylan Anthony

I think the most important question to ask yourself is “how long will we support deprecated features?” And then make the answer clearly visible to consumers.

Ultimately, the biggest concern that might lead you to versioning is compatibility breaking changes (things that would increment a semver major number). There are ways aplenty to prevent new features from breaking compatibility, so really breakage will just happen when you remove stuff.

If the answer to “how long will we support this” is “in perpetuity” then yeah, you need to version. If the answer is anything else, I don’t think you need to version. If your contract with your clients is “we guarantee compatibility for x months”, then it’s up to the users to check for updates at least once within that time period.

There’s nothing stopping you from versioning even if you limit support. If you do it would let you keep your code clean and just leave older servers / containers running until their support window ends. Separate servers also means you can check which client api keys are still using old services and proactively send them notifications.