I want to take you back to the fizzy and exciting times of 2016.
I had just exited the M.A.R.V.I.N project at VMware and was a little lost.
I had no mission and no goals. I was floating in the ether, looking for gaps, holes, anything that I could fill up with and hide for a while so that I could collect my thoughts.
A stranger with a smile
One afternoon in February or March, a gentleman named Akmal Khan approached me. Akmal has over 40 years of engineering and leadership experience.
We started talking, and instantly connected - his brain worked like mine.
Within a week, we were whiteboarding all kinds of crazy concepts, we didn’t have a mission, but we had buckets of invention ideas.
The gap
As we became friends and spent hours thinking out loud and drawing, a new initiative blipped on my radar: VMware Cloud on AWS.
Suddenly a flood of new REST APIs popped up, and we needed a cloud console to wire up all these APIs. Luckily the engineering team had chosen OpenAPI to document the APIs.
Akmal and I started looking at ways to automatically consume the OpenAPI specifications and create code for the UI.
We quickly realized that the Open Source landscape for OpenAPI was pretty bad.
Frankly, the landscape was awful (back then). There were tools for generating code (but the code was garbage), and there were tools for documentation that wasn’t very good at all.
There were also tools to validate / lint the specifications, but they were not performant or valuable.
The opportunity
We realized that investing in building bullet-proof OpenAPI tools would help us accelerate and dramatically reduce developer toil and bugs.
Akmal started coding like crazy, building low-level libraries and code generators that worked much better (and still do) than most tooling on the market.
It was successful! It worked and allowed me to step things up significantly with OpenAPI at VMware.
Project EVE
Fast forward to Summer 2019. It was the before times, before COVID - life was good. I had put together a pitch deck with Jehad Affoneh, in which we explained how we could re-imagine all the developer tools, docs, and experiences by adopting the OpenAPI Standard.
I pitched it to SVPs and GMs, who all bought into it; everyone did; it was a no-brainer. We got funded!
We called it Project EVE with a public-facing name of VMware DX
The first tool to build was a valuable linter for OpenAPI that we could use in our higher-level tools to measure quality. We looked at the market and tried out Spectral but quickly learned it wasn’t suitable.
JavaScript is excellent, but it’s not for everything
Stoplight built Spectral in JavaScript. We started feeding in our enterprise-grade, super large, and complex OpenAPI Specs into Spectral. 10-30 seconds later, we would get a result.
Thousands and thousands of warnings and errors made no sense and no idea how to fix them or why.
The experience was poor, to be honest—slow and mostly spewing noise.
It turns out building a fast, helpful linter is hard
After three months, the team abandoned the linter. It just wasn’t working, and it wasn’t adding any value.
It kept on blowing up or giving unhelpful results.
We failed hard. I was personally very disappointed, and I had done an inferior job of setting the right vision. If I knew then what I know now, things would be very different for that tool.
It’s the most critical element that a quality analysis engine needs. We needed to know the specification as a compiler does.
Without this component, I knew we would hit performance issues down the road.
We decided to pivot to focus on the next most important thing - documentation. More on that another day; for now, continuing to use Spectral for linting was our only option.
Le sigh.
The debt comes due
A year later, in early 2021, the rest of Project EVE is going well. We have built some excellent tools, one of which is called the Printing Press, which powers very large-scale OpenAPI documentation for VMware.
We had launched new API docs and PowerCLI docs, all generated from EVE tooling. Looking good!
But, it wasn’t all good.
I started working on some new services that depended on Spectral. These were real-time experiences, and speed was a hard requirement.
Spectral could not do what I needed it to do. Large specs choke the tooling.
There was no other option at the time - however, ReDocly has a much faster option for linting. ReDocly still suffers from the same problems at scale that Spectral does.
The technical debt I knew would come to bite had created a barrier with no way around it, and I didn’t have the time or the resources to solve the problem the way it is needed.
If you want something done
VMware built all the EVE tooling in golang with my direction. Without a golang linter that ran at least 1000x, the speed of Spectral, there was no way to execute my vision.
In October 2021, I decided to roll up my sleeves and do the hard work, on my own time, on my dollar. No-one else was going to fund the effort, except me.
I started building the linter I knew was required to accomplish many higher-level goals for OpenAPI tooling.
One requirement was that the tool is a drop-in replacement for Spectral.
How hard can it be?
The deeper I went, I realized that I had more and more problems to solve. Building a fully featured, extensible schema linter from the ground up is not easy at all.
I had to build the JSON Schema resolver four times. My designs were unstable and slowed down with scale.
My code didn’t hold up to testing, mainly because of the potential for highly recursive graph data structures. I stood in my kitchen at night scratching my head on many evenings, trying to figure it out.
My impostor syndrome was in full swing, and I slid into the pit of despair.
There were multiple points where I felt like I didn’t know what I was doing, and I almost quit twice. It took me months and thousands of tests to get it right. The solution was to change strategy and use an index design.
Learn more about how I solved the speed problems using an index.
Ten months later
But don’t take my word for it; try it with one of your OpenAPI specs below.
If you need a spec to try out, why not use the Petstore Example
vacuum is fully compatible with, yet exponentially faster than Spectral.
There are also unique features available in vacuum that aren’t available anywhere else, like a console UI and dashboard and vacuum sealed reports with much higher fidelity than Spectral.
See the speed for yourself
Designed for developers
Suppose you want to bring ultra-fast OpenAPI linting directly into your golang application. In that case, there is a straightforward set of APIs to do just that.
What’s next?
vacuum is just the first part of a much larger story that I am building around APIs and developer experience. I hope it helps you on your journey with OpenAPI and API quality.
Learn more about getting set up with vacuum in 30 seconds in this tutorial, or why you should care about API-First and quality analysis.
If you’re in the mood for code, you can read all of it on Github.