Design guides and governance

Proposals are Optic's version of the Pull Request—a staging area where you can discuss and revise API changes before accepting them into your current API specification.

When you first start using Optic, every API change is saved directly to your specification. This is like pushing to main on GitHub. It's collaboration, sure, but without the Pull Request it is difficult to review changes as a team or enforce your API design guide and governance.

Once you turn on 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.s for your team, every API change, both "code-first" and "design-first", will have a corresponding proposal.

Reviewing changes is governance

Helping the team review every API change before it gets deployed is the most effective form of governance. When a team discusses API changes, the impact on consumers, and how the changes affect their business, they build better APIs.

Optic keeps track of the API changes under review and those that are in design. You can decide if the changes need to be approved by anyone in particular in your organization, or if they have to adhere to certain design patterns or standards before being approved.

Proposals and the API Lifecycle

Each Proposal includes a set of API changes a member of your team is proposing. It includes a thread where your team can share feedback in the form of comments and track the proposal's status (i.e. Approved, Rejected, In Design, or Waiting for Review). Optic collects evidence associated with each proposal and displays it on the Proposals page.

please pardon the drawing, we're building this now!please pardon the drawing, we're building this now!

please pardon the drawing, we're building this now!

API changes, a review period, and 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. can be combined to support the many processes encountered on real-world teams.

Let's imagine a "code-first" change

Even if your team makes certain kinds of changes "code-first", Optic makes sure your team properly reviews those API changes before deploying them to consumers.

  1. A developer on the team makes a change to the API implementation.
  2. They use Optic to track this change, and open a Proposal in Optic. It only takes 2 minutes since Optic helps them document the changes using their development traffic.
  3. The team can give feedback on the Proposal and request the developer makes any important changes. At some point they'll mark it as "Approved".

Around the same time, the developer opens a Pull Request for the code changes:

  1. Optic automatically links your Proposals to the Pull Request in GitHub so code reviewers know that this PR changes the API.
  2. (optional) Before you approve the API changes, you might want to write a CI rule to block this PR from being merged.

Once the PR is merged, Optic can track the changes from your Proposal from CI all the way to Production using evidence gathered from your environments.

Let's imagine a "design-first" change

Many teams want to work design-first but find it difficult to achieve today. It requires everyone to learn OpenAPI, to diligently write manual specs, and buy (or more often build) their own tooling to make sure their implementation matches their specification.

Design phase: planplan - Planning a change involves defining the behavior of desired API changes for review in a proposal. The behavior desired can be defined with structured text such as OpenAPI, interactive edits to requests and responses, or structured data such as example JSON request and response bodies. Planning a change is the first step in design-first workflows. an API change

  1. In Optic, anyone on the team, even non-developers, can propose a change.
  2. To discuss a Proposal with all an APIs stakeholders before it gets built, when it is still cheap to change things.
  3. Eventually mark the API changes as "Approved".

Development phase: make sure the API design is implemented correctly.

  1. Developers read the proposed API design in Optic and build the API change it describes.
  2. Developers show Optic real traffic when they're finished to provide evidence of an implemented API design. If Optic finds a problem, it helps the developer implement the design correctly.
  3. When the developer opens a Pull Request, Optic automatically links to the proposal and comments on the thread "This PR is known to implement API proposal XYZ".

Once the PR is merged, Optic tracks the changes all the way to Production using evidence gathered from your environments.


Did this page help you?