How evidence works

In the real world, there are always multiple versionversion - Defined behavioral expectations for an endpoint or API at a point in time. Once a proposal is approved, it becomes the next version of your affected endpoints.s of our API running at any given time:

  • Each Pull Request + CI run may include new or updated API endpoints or partial implementations of an API design.
  • Production, staging, and canary are all running different builds with their own set of API behaviors.

Manual API specifications like OpenAPI are hard enough to keep up-to-date. When you confront the reality that the API is going to behave differently across environments as a natural consequence of your development lifecycle, it gets exponentially more complex to keep track of it all.

Optic automatically models the behavior of your API across all the environments with evidenceevidence - Real traffic to your API. Evidence verifies certain API behaviors across specific commits, builds and environments. It provides a link between your specification and your API's behavior in reality..

Questions Evidence can answer:

What is evidence?

Evidence is the link between your API specification and reality. It is collected by monitoring real traffic and matching API behaviors across specific commits, builds, and environments.

Imagine an API with 3 endpoints. The API tests run in CI and there is a staging environment and production environment. The team is working design-first. Anna, a developer, is working to implement the GET /posts endpoint her team has designed. She just opened PR -153.

In the Optic Dashboard, you can see the state of the entire API across all environments:

  • Notice how Optic knows GET /posts 1.0 is running in PR - 153. Optic noticed this PR is the very first implementation of GET /posts it has seen.
  • Notice that GET /**posts** is listed as N/A in Staging and Production. This is because Optic has never seen the new GET /posts endpoint in either of these environments. That makes sense, as it's still being reviewed by the team and was never deployed.

GET /posts

GET /users

POST /login

CI
PR - 153

1.0

1.5

1.1

Staging
Build - 643

N/A

1.5

1.1

Production
Build 637

N/A

1.4

1.0

Now let's suppose the PR is merged to the develop branch and automatically gets deployed to Staging after a few minutes.

GET /posts

CI
PR - 153

1.0

Staging
Build - 643

1.0

Production
Build 637

N/A

Then they merge it into Production. By the time it gets there, a small non-breaking change was made in PR-155, and the cycle continues.

GET /posts

CI
PR - 153

1.0

CI
PR - 155

1.1

Staging
Build - 643

1.0

Production
Build 637

1.0

At any time, you can go into the Optic Dashboard or call out to our API and understand which versions of each endpoint are running in each environment.

If you go back to the original 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. where the team designed GET /posts, you'll see the lifecycle diagram for the specific changes in that proposal:

  • Approved by Roger 2 days ago.
  • Implemented by Anna, in PR - 153, 1 day ago.
  • Appeared in Staging 12 hrs ago.
  • Appeared in Production 7 hrs ago.

With Evidence, it's easy to track every API change, code-first or design-first, from approval to production, and react to these transitions from one version to another.

Evidence is automatic

Evidence just works. You don't need to manually update any of the semantic versions or tell Optic where certain versions are expected to run. Optic collects evidence and aggregates the state of your API across all the environments.

All you have to do is configure your evidence sources. Evidence sources are agents that run with your tests or in your deployed environments, look at the traffic, and send information back to Optic about which versions are running.

Evidence can be collected from:

  • API Gateways and Load Balancers (Kong, Goo).
  • Service Meshes (Envoy or Istio).
  • From your Docker containers (using a small background process).
  • Using a Proxy.

What’s Next

Learn how to set up evidence and get it logging back to Optic's Dashboard

Did this page help you?