Document your Internal APIs in 10 minutes

It’s 2019, Microsoft is cool again, oh, and APIs still suck.

Sure, there are some well documented and easy to use public APIs, but most of the APIs a developer works with on a daily basis are not documented, easy to learn, or fun to use.

At Optic, we are on a mission to make APIs developer friendly. Today we’re launching the open source Optic API CLI to make documented APIs the default.

Try it now

Introducing the Optic API CLI

We built Optic’s API CLI to make maintaining accurate specs for your APIs automatic and developer friendly. Once you add Optic to your API repo, it automatically tracks your API’s behavior and maintains a change log of its behavior over time.

It’s kind of like Git, but instead of tracking files, Optic automatically diffs and tracks API endpoints. Here’s a video of the API CLI in action:

How It Works

Add Optic to your API’s repo by running api init. Then, tell Optic which port your API runs on during development, and the command used to start the API.

Once setup, use Optic’s ‘api start’ command while developing and testing your API.

When ‘api start’ is used, Optic stands up a local proxy that watches the incoming traffic and behavior of your API. Using this data, Optic constantly computes the diff between your API specification and the actual behavior of the API.

Similar to how Git can generate a diff of your file system, Optic can show you a diff of your API contract.

• If you updated the API intentionally, Optic asks you to Approve the changes to your spec. This is much easier than figuring out what you changed and rewriting the specification manually.
• Optic will also catch cases when bugs are introduced that changes the API behavior unexpectedly. 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.

Benefits

• With Optic’s API CLI, you can be confident that your API spec accurately describes the current behavior of your API.
• 100% Open Source, Runs locally, data is only stored in your API Repo
• Undocumented APIs can quickly be documented using Optic
• Unexpected changes to an API’s behavior are caught in real-time, before making it to staging or production
• OpenAPI files only describe a snapshot of your API’s behavior, Optic also stores a built-in change log modeling the evolution of your API over time.

Design First

What about design-first API workflows? Optic ships with a beautiful API designer (its like an open source Stoplight). If you want to design your API contracts before building them you can do it right from within Optic’s visual tool.

We even take it a step further…

Because Optic is monitoring your API’s contract and its real-world behavior, we can tag everything in your API spec as “Designed”, “Implemented” or “Broken” automatically. This instant feedback makes actually implementing the API much easier for developers and allows API designers to monitor their progress.

You can also design your APIs with less detail than a typical design-first workflow requires. Maybe you just want to define your paths and write descriptions, but you’re not sure what some of the request bodies will look like? That’s fine! Once the engineers implement the code they can merge in those implementation details into the spec for your review.

We’re looking for 3 more teams that want to test the Beta version of the design first features we described above. If you want to help guide the development of this feature and access to it before everyone else, sign up here!

Our Focus

Optic’s focus for the rest of 2019 is to build the best API Designer on the planet. We’re going to work hard to make the API CLI the default for documenting APIs and tracking their evolution over time. When it comes to API projects, we want it to be as prevalent as Git.

On the Longer Term Roadmap

• Breaking Change Management — Detect breaking changes AND get automatic impact reports detailing which teams/developers those changes will affect.
• Standards Enforcement — Write and deliver API standards with Optic’s linting rules. Drive teams towards your patterns as they design and implement services.
• SDKs — Use Optic to generate high quality SDKs for all of your APIs. Consumers can install these client SDKs using the API CLI as the package manager.
• Advanced Mocking — Use Optic to mock your APIs. Since Optic understands your spec and can collects real examples it can do much more advanced (even partial) mocking. Stay tuned…
• Real-time feedback — Get real time feedback from Optic as work to integrate an API. Optic will provide actionable suggestions to help you complete integrations to any API quickly and without the headache.

Getting Started

We hope Optic is helpful to your team. If our tool sounds interesting, here’s some links to get you started

• Schedule a free on-boarding session with Optic’s creators. This helps us as much as it helps you. Plus, we’ll mail you some swag to say thanks :)
• Click here to try Optic on your own

Interested in helping out? We’re 100% open source and you check out our code, open issues and contribute back on our Github.

We look forward to helping you make APIs more developer friendly on your team :) Thanks for giving Optic a try.