Optic is a Git-like version control system for API contracts. With Optic, maintaining an accurate API contract is as easy as reviewing diffs and approving suggested changes.
Optic is designed for HTTP / RESTful APIs. It will not help you with websockets, event-driven APIs, GraphQL endpoints or RPC-style APIs. We may add more Optic-for-x-paradigms as the project grows.
Optic’s CLI monitors the HTTP traffic going in/out of your API process and therefor, can work with most API frameworks. We’ve taken the time to write tutorials for 20 popular API frameworks in Node, Python, Ruby, PHP, Go, Java, C++, and Rust.
Most developers can get Optic running in their local development environment within 10 minutes. Follow along with our setup instructions.
Keeping your docs up-to-date should not be a chore. If you are documenting your API manually or adding annotations throughout your source code to generate the OpenAPI, Optic can simplify your workflow and improve the accuracy of your docs. Optic also supplements your testing, catching API changes before they propagate from your local development environment.
Optic and OpenAPI are compatible with one another and share many of the same goals. What makes Optic different is its focus on building developer-friendly workflows that make it easy to document your API and verify that it is meeting its contract.
Optic acts as a proxy for traffic to your API. It observes request and response traffic, and summarizes the shape of the data. You can build documentation and commit changes in behavior during a capture with the Optic Dashboard.
Captures are sessions that observe a single run of the target API application. When a code change is made and the application recompiled, Optic will see this change and automatically start a new capture. This helps organize testing and works in progress.
Optic helps catch unintended changes in API behavior, and any developers working on your API project should have Optic installed. The
.optic folder where Optic stores the API contract may be checked into your repository when commiting your code changes.
Optic has no impact on performance, and we recommend running it at the start of your development session and keeping it running until you’re done with work for the day and ready to shut down. Optic will automatically detect new builds of your application and organize the traffic from those builds into captures.
Optic needs to be able to inspect the traffic, and if you use SSL/TLS in your environment Optic would need to run after the SSL/TLS termination. Optic provides a
baseUrl configuration to set up a hostname and port for the Optic proxy as well. See our configuration page for more information.
Every environment is different. If you need some additional help, schedule some time to meet the maintainers and dig into your setup. You can also search GitHub Issues for a similar setup, then open a new issue if you don’t see one that fits.
Optic is currently designed to help developers document their API and catch unexpected behaviors at the time of development. We’re working on bringing Optic further into the software development lifecycle and adding value to other project users, including consumers. If you have a strong use case, search our GitHub Issues to see if someone else has submitted a similar user story. If not, open an issue and let us know where else you think Optic could help out!
As always, feel free to schedule some time to meet the maintainers.
Ready to try Optic?
Optic is distributed under the MIT license.