Why do we miss things during API review?

Aidan Cunniffe 2022-07-05

When we’re reviewing each other’s code it’s a context change from whatever we were doing before. We’re still thinking about other tasks, but to do an effective review we have to build context about what our teammate is working on. When there is any friction at all in this process, the quality of the review goes down.

That's why best code review and CI tools were designed and built for busy humans. All the context needs to be right in front us us. On GitHub you can scroll through all the code changes, you don’t need to click around a file system or move windows around.

We ask new Optic users to tell us about last few API problems their team faced. Usually they tell a story about some problematic design choices and breaking changes that got released to production. They can not understand why these changes are not getting flagged for discussion during code review. One user shared “We know how to do this, but we do not do it together yet”.

When we look at how Git renders OpenAPI changes, it’s not hard to imagine why teams struggle with API Review:

Updating a shared component

Which components are updated? You can’t even see the names without expanding. Where are these $refs used? Is it in one operation? Several? Are they parts of requests, responses, both? A busy code reviewer would have to load the entire file and start searching for the component names to figure it out.

Missing Context

What API operation is this being added to? Has that operation been released to the public yet? If so, adding a new required parameter is breaking, if not this is probably ok?

More signal than noise.

Ok what’s changed? Nothing, actually. Refactoring your API spec looks like changes Both versions of this OpenAPI file describes the exact same API behavior.

Teams frequently refactor their specs to add / remove $refs, reorder things, and split their OpenAPI across many different files. Optic knows these aren’t real API changes.

Some teams have used Optic as an aid while they refactor to ensure that in the process they didn’t change anything material.

Messy lines

What’s happening here? Looks like cookies were added to the default response?

Or were they? Because of the way Git computes line diffs sometimes lines from different OpenAPI contexts get mashed together in a confusing way. It turns out these changes were to an entirely different operation:

Making OpenAPI changes reviewable

Maybe the simplest solution to improving the quality of your team’s API reviews is the right one: just make it easy to see what’s changed and start a conversation about it.

Optic visualizes API changes, but instead of organizing them around files/lines, like Git, Optic organizes the changes around API Operations, parameters, bodies and properties. This makes it much easier to understand the scope and impact of an API change.

Teams have reported that adding Optic’s visual changelogs has very quickly improved the quality of their API reviews, leading to better design choices and fewer issues. If you've had this problem, give Optic a try: