Plan a change

Building a great API that meets the needs of consumers requires good planning and lots of feedback from stakeholders.

Optic helps teams:

  • 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. their API changes before building anything in code.
  • get feedback from stakeholders early.
  • verify each API design gets implemented correctly in code. Make it easy for developers do it right!

Inclusive API design

Any stakeholder should be able to participate in API Design and Review. You do not need to read and write OpenAPI documents to help build a great API.

In Optic, API design can be done by writing examples. Examples have a lot of advantages over writing schemas:

  • much more accessible, not just for developers.
  • easier to discuss and revise than schemas.
  • examples can be transformed into schemas when it's time to build the API.

Open a 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., provide a URL, and add some example requests and responses. If you'd like to write a JSON schema or add OpenAPI, that works too.

Either way, your team sees a nice API changelog during review—it's easy to read, and allows more people from your team and your consumer's team to understand and give feedback about the design.

Feedback and design review

Within your Optic project, you'll see a list of the open Proposals:

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!

Inside each proposal you'll see an API changelog, and a thread of comments. You can give feedback here, discuss design options and make changes to the original proposal by updating its examples.

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!

Eventually, when the API design is agreed-upon, it can be marked "Approved" and will appear as a new version in your API specification.

Since it may take days or weeks for these changes to get built and appear in real environments, Optic automatically tracks the implementation and deployment status for each of your approved Proposals using evidence.

Help developers implement the design

When it comes time to implement the team's design, developers are stuck doing a lot of manual comparison between the implementation's behavior and the schema they're building against.

How do we know if we did it right? Did we miss an important detail? Will a consumer trying to use the API find an error or omission in our work? How can we show our work, and prove to our teammates that we implemented the design correctly?

Optic helps here too. Any developer can open an Approved Proposal, and click Provide Evidence of an Implementation.

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!

Optic looks for 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. of each request body, request parameter, and each possible response. If the traffic you show it does not have coverage for something in the design, like a certain status code, Optic will ask you to send traffic to show it that status code.

  • If everything passes validation, Optic will certify that the API is working as designed.
  • If the implementation is slightly off, Optic will give you a todo list and guide you through making the required changes.

Now that the API design has been implemented, Optic will update the status of your Proposal to show which Pull Request implemented the Proposal.


What’s Next

Proposals are like Pull Requests for your APIs. In addition to anchoring API review and discussion, they are the ideal place in the workflow to enforce design guides and governance rules.

Did this page help you?