Vimeo + OpenAPI
Over the past year or two, a common question we’ve received from the Vimeo developer community has been, “When are you going to offer an OpenAPI specification?” That day has arrived.
The Vimeo API is now available as an OpenAPI specification on GitHub, and also through our API!
Migrating an API of our scale to a specification format certainly wasn’t an easy task, so how did we get here?
Evolving our API design process
Two years ago at Vimeo, we decided to migrate our API design process from GitHub tickets and Google Docs to API Blueprint. Adopting API Blueprint enabled teams within Vimeo who weren’t familiar with API design to pick up how to model API resources easily. It also enabled the API team to review them quickly and use these specifications as a… blueprint… for asserting that the end result matched the anticipated result.
Getting to that point was a problem, however, because we didn’t have API Blueprint specs yet, and we had no way of constructing them. And as much as I love doing remedial tasks while watching 80’s slashers, there’s no way I was going to manually build and continuously update these.
☴
We did, however, have a small internal library called Docparser. Docparser was a small DSL that enabled us to write API documentation as code comment annotations within our codebase, convert that into an array, and render it back out on our developer reference pages. It wasn’t without its problems, though.
Nobody knew how it worked, since it had been built years before and mostly forgotten about, and usage throughout our codebase was spotty at best. New API endpoints and features weren’t even being documented anymore (because nobody knew how to), we had no way to version changes between versions, and documentation we did have on our developer site was sorted by how its filename was located within our codebase. Hope you like having to spend time hunting around a navbar to find what you’re looking for!
Not to mention that we had zero documentation for what we returned in the API.
A straight-up horror show. 😱
So I sat down one late afternoon and started writing unit tests. Dang, this endpoint is missing a label! How could we be so careless? Let’s add some validation. Ah, rats, we need to return a different response on this endpoint for a newer API version, let’s add a new annotation for that. Oh, right, we don’t have any way to document API response schemas, we should probably have that. We also need the ability to compile API Blueprint files, imma do that too.
Next thing I realized was that I had completely rewritten the library. So we decided to open-source it. Say hello to Mill.
Mill, like its predecessor Docparser, is a PHP library (we’re a PHP shop after all) that enables us to annotate our API codebase with comments that can then be compiled into a machine-readable collection (and then further translated into other formats).
Here we’re documenting our /me and /users/:id endpoints, and the schema that it returns. It can definitely, and does, get complicated from here, but this is a very simple example. From here we can run a single command, ./vendor/bin/mill compile — format=apiblueprint specs/, to generate an API Blueprint specification for each version of our API.
And since Mill has full knowledge of our entire API, it can also do rad things like generating automatic changelogs, which you can see at https://developer.vimeo.com/api/changelog.
While our annotations are plentiful, they aren’t the source of truth for the API, and they’re maintained separately from the rest of our application business logic.
Adopting OpenAPI
Around the time we were wrapping up integrating API Blueprint into our API design process, Swagger had been adopted by the OpenAPI Initiative, and work on specification version 3.0.0 was in full swing. Now that Mill was compiling our documentation into API Blueprint specifications, OpenAPI was picking up steam in the API world, and we had internal teams looking to build tooling with it, we decided that it was time to join the party. The hard work had already been completed on our end. We just needed to build a new compiler.
Since completing OpenAPI compilation support in Mill back in June, various teams at Vimeo have been slowly adopting it: our front end team has been working on a TypeScript library to do build-time validation according to what we return in the API, our Android team has been rebuilding our Android SDK in Kotlin using OpenAPI-generated models, and we’ve fully rebuilt our entire API reference documentation and playground to be powered by it.
Now it’s your turn to build something cool.
Supporting OpenAPI, and building Mill, has been a huge passion project of mine since joining the team, and I’d like to extend an amount of gratitude to the rest of the API team for the countless (large) pull requests, and the Engineering organization on a whole for having to learn and relearn, and relearn, some documentation syntaxes as we grow our documenting capabilities. Thank you for your patience over the past two years.
I am elated, and relieved, to be finally releasing this to the greater development community.
You can access our OpenAPI specification either by going to https://github.com/vimeo/openapi or by accessing https://api.vimeo.com/?openapi=1 with a valid API access token.
