Showing your work with Optic

API changes should be documented and reviewed before getting deployed to consumers. Sounds great, but in order for that to happen, developers working on the API need an easy way to show their work. Imagine if you had to author your Git patch by hand instead of using git add and git commit—no one would do it. That's why most OpenAPI files are incomplete and out-of-date.

That's the first problem the open source project sets out to solve: how do you make tracking API changes and history as easy as using Git?

When you want to track a change to your API, you show Optic real traffic, which it diffs against your current specificationspecification - The current API specification, and a full history of every change ever made to the API.. Any API diffs it finds (i.e. 3 new fields included in the 200 response) become part of a patch (just like git). It's quick, much more accurate than writing the patch manually, and helps you and your team build confidence in the API's behaviors.

How it works

Let's say you are implementing a new endpoint GET /users/:userId/orders/returned:

  1. First you write code to implement this new capability, along the way you're testing it in Postman.
  2. When you get the API working the way you want it to, you open Optic and click + Add Endpoint.
  3. Use Optic's Capture Toolkit to collect example traffic Optic uses to document your changes. Optic uses the traffic to document the new endpoint and check it into your specification.
    this is Optic's git add
  4. When you open a Pull Request, Optic automatically includes an API changelog.

This workflow is similar to what you would do manually. All you are really doing is handing off the tedious work of comparing your API implementation to the current spec and authoring a correct patch.

In summary, Optic gives you a Git-like tool to document your API changes as you make them:

Beyond showing work

Once everyone on the team is showing their work, API Review becomes a part of your existing Code Review process.

Learn more: Review API changes

Sometimes it makes sense to plan changes ("design-first"). Teams that work this way often struggle because there's no easy way to make sure the API actually gets built as designed. In Optic, developers can click + Verify an implementation on any "design-first" proposalproposal - Conceptually, "API Pull Requests". Proposals are WIP changes the team is discussing / revising until they're ready to be "Approved". After approval, the affected endpoints include these changes as new version. and get Optic's help implementing the API as-designed. Zero diffs means a working implementation.

Learn more: Plan a change

Connecting our API specification to reality has never been straightforward. How do we know if someone on our team accidentaly changed the API? How do we know which version of the API is running in each environment? Optic answers these questions and more by passively gathering evidence of your API behaviors from CI, staging, and production.

Learn more: How evidence works


Did this page help you?