This guide is designed to give you an overview of what it's like to use Optic -- without having to download the tool or set anything up locally.
- Since Optic looks at API traffic, it's language agnostic and works the same with any REST API stack. The community has written over a dozen stack-specific guides.
- The Rust binaries that do all the heavy lifting are tested on Mac/Windows/Linux
- Get the benefits of accurate OpenAPI specs without having to learn OpenAPI and write lots of YAML.
api is Optic's open source CLI. It observes your API behavior locally, and processes all traffic on your machine using a really fast Rust binary.
Next you add Optic to your API project. Just like
api init will add Optic to your project and start tracking the history of your API.
3. Configuring tasks in
When you start your API or run its tests with our CLI, Optic is able to observe your API's behavior and diff the traffic against your current specification. You tell Optic how to start your API and run various test suites in your
optic.yml file. There's a wizard, and plenty of guides in the docs explaining how to set these up.
Once you have these common commands for your team aliased, using Optic is really easy. You just replace
old command with
api run <task> -- we named it
api start is really easy to remember.
Just like a new Git repo is empty, a new Optic project has no endpoints documented, and no history for your API. Luckily Optic makes it really easy to document your API just by looking at its real behavior.
Let's do it: Run all your tests, go crazy with
curl stuff, use Postman, your webapp, whatever you can to exercise a bunch of the API surface area.
You don't have to worry about hitting every possible request/response your first go -- Optic isn't "one-shot", it builds your spec up incrementally as it makes more observations about your API's behavior. For example, if Optic sees a 200 for an endpoint, and later sees a 400 for the same endpoint, it will help you add the new response.
After collecting traffic for a few minutes, you can jump into the UI and start documenting the traffic Optic saw. In this example, see GitHub's API, most users can document all these endpoints in 2-3 minutes:
Hover to Start Interactive Demo
Optic is constantly monitoring your API's behavior and looking for unexpected diffs. 95% of the time your API isn't changing and Optic is invisible.
You'll be glad it's there when:
1) You make intentional changes to the API, ie adding a new field or adding a set of endpoints. Optic makes documenting these changes and sharing them with your team super easy -- esp compared to manually writing OpenAPI
2) A code change causes an unexpected API change/regression -- sometimes changing one class property affects 30 endpoints, or you add some debug info to an API response that you forgot to remove. Optic catches these changes.
status command checks your recent work for API Diffs:
When Optic detects changes in your API behavior, there's a nice UI to Review them.
- If the changes are intended and ready to share with your team, Optic will help you patch your API spec with a few clicks
- If the changes are unintended, Optic will show you the problem and help you fix the API
Here's an example of a change in the GitHub API you can review with Optic:
Hover to Start Interactive Demo
Optic was built to give teams a developer-friendly workflow for keeping an accurate API spec, and managing changes to their APIs.
You check in:
optic.ymlfile to share your
api run <task>aliases with your teammates.
.opticfolder which contains a complete history of every API change since
api init. You'll be able to come back months from now and play your API history forward / backwards, see which endpoints are most stable/changing, and plan future changes.
Install the Optic GitBot -- it makes API changes explicit during Code Review, so your team understands how the API will change when the PR is merged.
🚦 Prevent Breaking Changes -- Discover breaking changes before they're merged. Request compatible changes in code review, or coordinate the breaking changes with consumers.
🔎 API First -- Adding explicit API changelogs in PRs facilitates discussion and leads to better API design. It's also a great way to make sure unintended API changes don't get deployed.
✅ Updated Docs -- No more doc drift. When you approve an API change Optic also updates the specification.
Look cool? Want to give it a try? Add Optic to your API
We're working on a lot of cool stuff over the next few months, if you want to help us design these capabilities and get early access, schedule a meet the maintainers call
- Run your CI tests with Optic to add an automated gate on breaking changes
- Use Optic's design-first mode.
- Run Optic in staging + pre-prod environments