"Git for APIs"?

I'm really happy to say I've started a new job at Optic, and with this comes the learning process of getting more depth with new technology and its use cases.

So let's start with the tagline for Optic, what does "Git for APIs" mean? And why should builders of APIs care?

Before we describe why Optic is the Git for APIs it'll probably be good to cover what Optic is and what problem it's trying to address, to begin with. How about the problem first? I don't know about you but I hate writing API documentation, it's hard to keep up to date when whatever you're building is moving faster than the time you have to sit down and process the changes you and your team have just done. You'd have thought we'd have automation for this by now? Optic is an open-source tool that helps to document your APIs and any changes they may have by making it easy to visualise and analyse the changes of actual HTTP traffic flowing into and out of your application. What this means is if you make requests to POST /hello/world, POST /hello/universe, and GET /hello/world Optic will keep a record of them for you to review later. This makes it super simple to check when new endpoints have been added, or when endpoints have been modified, and from this information, you get a specification of the API and a changelog of the API too 🤯

Yes, that's right, a tool that helps to generate documentation of your APIs, and make sure that the changes don't get lost in the mess of PRs that flow through your applications build and life-cycle.

And this is where the Git for APIs bit kicks in, once you've gathered up the different endpoints in real-time you need to identify the URL structures. And over times the URLs and schema of the body will change, Optic provides the tooling to cover this.

So initially you get a view that allows you to identify the endpoints, and thus the initial structure of the request and response. This in itself is amazing, documentation of your API without spending forever hand-cranking an OpenAPI Spec file. But then the next super clever piece is that it provides you with a list of changes, so edits to the endpoint with additional or missing parts of the request or response. And it shows you those changes as a diff, similar to how you would see it in Git… and now we know why it's got that lovely little tagline.

Now you can start thinking about the use cases, and as a lazy developer what it can automate or even stop me doing bad things. Like Optic already has a git bot to automate check to make sure you've documented the API, but just think about automating PRs or changes to client libraries or anything else!

And just as a little extra niceness, the new version 10 release is landing soon so more features and UI improvements incoming!

I'm also enjoying learning how the tool is built and evolved. It's a whole bunch of tech inside a small tool, it's JavaScript, TypeScript, Rust, and Bash… I kind of love how the tools have been picked for the best bits.

What use cases or ideas about how you'd use Optic, we'd love to hear about it? You can join our community at https://useoptic.com/docs/community/, email me at mike.elsmore@useoptic.com, or get me on Twitter at https://twitter.com/ukmadlz. See you all soon.