Optic Blog

An API Changelog on Every Commit

Over the past several weeks we talked with API engineers and architects about the biggest gaps in their current API tools and workflows. One story that's come up over and over is the need for better changelogs. When changes aren't written down and communicated effectively code breaks, builds fail, releases get pushed back and a lot of developers are left unhappy. Semantic API changelogs that are both clear and actionable seem like a critical piece of infrastructure that most teams don't have in place today.

Optic's Changelog Git Bot

What if every time an API was updated, you got a corresponding semantic changelog for free? We heard that this would be useful from enough teams that we put our heads down and built an MVP this weekend.

The result was the Optic Git Bot. It checks every commit for API changes and posts a semantic API changelog when it detects changes. Here's a real example of a changelog Optic generated for one of the APIs we've built internally for testing:

That's it. Plain and simple, but it's easy to imagine this saving teams many hours a month. We're going to iterate on this a few more weeks and then release it.

If you want to join the Beta click here. 10 spots. First come first served.

What about Git? Isn't that my Changelog?

Using Git to track changes in OpenAPI specs is the industry standard, but when you look deeper, the approach quickly breaks down. Line diffs like those Git provide do not tell anywhere near the whole story.

Let's take a look at a recent example of Stripe updating their OpenAPI spec. Here's the link to the commit on GitHub: https://github.com/stripe/openapi/commit/c806fa1f987eba8cac1a9842fb959b226de099a0

  • The first problem is that line-diffs only show 3 lines above and 3 lines below a change. This completely erases the context. What's going on here? It looks like a field called 'revision' was removed, but from which endpoint? Is it removed from the request body? If so it's not a breaking change, but if it's being removed from a response then that is a breaking change. How is a developer supposed to react to this?
  • What about this? Since we know a little bit about OpenAPI we can guess that digital_good_applications is now required. But...why does it show up four times? Which endpoints are affected? Is it now required in a request body, if so that's a breaking change! Is it now required in certain endpoints but not others? What does any of this mean? 
  • Another issue is one of lost intent. Since OpenAPI doesn't have a notion of changes in its core domain, interpreting a diff entirely programmatically isn't possible. If I renamed a field foo -> bar, a structural diff would say query parameter "foo" deleted and query parameter "bar" added instead of "foo renamed to bar".
  • Lastly, there's a huge abstraction distance between a DRY OpenAPI spec and the changes I as a developer care about. For instance, if I see three fields added to a shared schema, I have no idea what endpoints are actually affected without CTRL-F-ing around and mentally flattening the spec.

Line diffs are just the wrong tool for the job and OpenAPI codifies a snapshot of an API's behavior, but has never been concerned with codifying the evolution of an API. A lot of really smart people have tried to make good OpenAPI diffing tools and automated changelogs without much luck. The problem isn't tractable with the current framing.

Optic gets around these challenges because our spec format is essentially a changelog. You can think of it as an event-sourced OpenAPI. We designed Optic this way because we believe that understanding the way an API changes is often more important than understanding how an API works at any point in time. Evolution is baked into Optic's the core domain which made building the diff bot entirely natural.

We look forward to hearing your ideas! If you want to be one of the first teams to use the Git Bot, you can join the Beta click here