Most APIs are not documented and many of the APIs that are documented are not documented accurately. Across the industry, we're seeing exponential growth in the number of internal, external and partner APIs.
But how can we keep up with this explosion of new services? We have to make well documented APIs the default.
Start your API server using Optic's 'api start' command.
You can think of Optic as a side-car that documents your API as you develop it. You can run it while developing on localhost or in your development environment.
Using traffic to document the API, ensures that the spec describes API's actual behavior.
Developers do not like writing docs, and they especially don't like updating their API specs manually. Optic makes updating your API spec almost automatic. Similar to how Git can generate a diff of your file system, Optic can show you a diff of your API contract.
Whenever Optic observes your API behaving in a way that deviates from the API's spec, it notifies you in real-time.
It's then up to you to Approve these changes to your spec (merge). This makes updating your API spec as easy as a few mouse clicks.
If you accidentally introduced a bug to your API, you may catch it here. Let's say you started returning a sensitive field in a response -- Optic catches this in the diff and lets you mark it as a bug.
Many teams choose to define their API's contract before building the service. Optic ships a beautiful API designer. There are powerful features built-in that help teams enforce their API standards for security and conformity.
In design-first mode, you can model your API visually. Then when it comes time for implementation, Optic gives the developers live feedback to help them debug code and track their progress against the new requirements. Optic also tags different endpoints based on their status and lifecycle. For example, all your endpoints are automatically tagged as 'Designed', 'Implemented', or 'Breaks Contract'.
Optic works with any Restful API written in any language / API framework. The side-car architecture makes it portable so you can run it in development, locally, or to catch issues/validate contracts in production (talk to us about this if you're interested).
All you have to do is switch one behavior: start using the 'api start' command.
Developing your APIs with Optic running is like having a pair-programmer that's only concerned with making sure your API contracts are documented and implemented by the clients and the server.
Because Optic runs in real-time, your API's contracts will always be up-to-date and you're protected against making breaking changes to your API contracts.
We'd love to hear your feedback and, if you're interested, help you setup Optic for one of your APIs.
Thanks for reading! Let's work together to get every API documented.