OpenAPI Versioning just got easier

Aidan Cunniffe 2023-02-10

Many of the teams using Optic build internal APIs — they still want to prevent breaking changes, but occasionally they decide breaking the API contract is the best path forward. They send an Optic changelog to their consumers, coordinate the release, and (hopefully) it all goes well.

Some users have been asking our suggested workflow for making breaking changes — should they ignore warnings from Optic? Merge past the CI failures? Turn off breaking change rules then turn them back on?

On a call this week a developer suggested we use the semantic version in the OpenAPI file. If they made a major version bump, then breaking changes will be allowed. We immediately that might make a lot of sense, and threw up a quick PR.

Let’s look at an example:

  • Optic catches the breaking change: created_before as a required query parameter
  • It fails its checks
  • When you bump the major version the change is still detected, but the checks pass
Major API version can have breaking changes

We are thinking about going further with this idea and publishing a new ruleset called semantic-versioning — it would make sure that info.version is changed to match the kinds of changes you have made (be them major, minor, or patch). We’re still trying to decide exactly what kinds of API changes are minor vs patch, if you want to weigh in join this discussion on GitHub.

That’s all for now! Optic team :)

Want to ship a better API?

Optic makes it easy to publish accurate API docs, avoid breaking changes, and improve the design of your APIs.

Try it for free