Improve your APIs with Optic

If you are an API Developer or an API consumer, you know how important it is to keep your contracts up-to-date all the time. If you change something and don't update the contract, someone somewhere gets mad 😡 !

So here's a tool to help make friends of API consumers 👫 .

What?

Optic is a "Git-like version control system for API contracts". It makes it easier to create API documentation and update it as you go on merrily change your API request and response. All you have to do is review the change and approve it.

Installation

You can install the CLI as an npm global package or using homebrew.

It works with most of the languages - Java, NodeJS, Go, Rust, etc.

How?

Optic uses a proxy to monitor the API over the network. It detects any change in your API and suggests changes in your API documentation.

You navigate to your Project's root and run

api init

This creates a optic.yml in your project that you then navigate to and update with a couple of things

1. command - Command that runs your API Project. You also need to set the server port to be $OPTIC_API_PORT. This is a sample for a Maven Java project
   

   export SERVER_PORT=$OPTIC_API_PORT; mvn exec:java -Dexec.mainClass="com.test.Application"`
   

2. inboundUrl - Your API hostname and port. Like http://localhost:8080

Then there is a way to check if your configuration is working ok.

api check start. The check prefix verifies your configuration and then start starts the API.

There are a few other commands to help API developers

• api generate - This generates an Open API documentation that you can then use to host somewhere and have it used as a UI, like your Readme, Swagger UI, Slate etc.
• api spec - Opens your Optic API specification in a browser

I created a sample Spring Boot Ping API and set it up following the documentation. I got it up and running in a few minutes and it was finding endpoints and suggesting documentation right away.

For all the API Developers, this solves a major pain point of documenting the APIs while they are being developed and also keeping them up to date as and when changes are made. And it does so, all by snooping into your local traffic while you code away !

Why I love it !

GitBot - Apart from doing all the documentation for you, it has a github integration that would comment on every Pull Request, Detect any changes in your API and comment that in your PR ! Right there for the reviewers to see what you have fixed (or broken).

Look Ma, no YAML ! - (Well almost) There's only a few lines of yaml that it expects you to write. All other the other Open API specs to get that beautiful documentation, done for you.

API Test Coverage - With integration for running the tests through Newman (you will have to define a task in your optic.yml), you can use a --collect-coverage flag to ask Optic to track API testing code coverage and report that to you. It will look at your API Documentation Responses, and highlight any responses that you have not written a test for. So no more forgetting the edge case in your API Automation Testing !

Conclusion

I think it's a great tool that has a lot of potential use for any company developing APIs and need to keep track of their changes. You can add it to your build pipeline and use that code coverage tool in the CI pipeline. It is definitely like source control for your APIs as they advertise.

Also, it's free and open source. So you can fork the repo here.