api-design

Goodbye Apiary.io, You'll Be Missed

Today we say farewell to a legend in the API documentation space as O.G. API design-first solution Apiary.io shuts its doors.

Phil Sturgeon

04 Aug 2025 — 7 min read

Apiary.io was the first API documentation tool I ever used, and helped pioneer the API-design first workflow as we know it today, and now that it's finally being shuttered after being absorbed into an amorphous mega-corporation purely as a user aquisition exercise I wanted to say a few words.

Apiary.io was founded in 2011, bringing modern looking “Stripe-like” three column API documentation to teams which would otherwise have been documenting their API with a horrendous CMS or Wiki. OpenAPI didn’t exist back then, and Swagger was still incredibly difficult to work with with minimal tooling outside of the SmartBear offering, so they created their own description format: API Blueprint.

Unlike Swagger/OpenAPI which is based on JSON/YAML, the team pioneered a brand new approach, making API Blueprint based on Markdown. This made it very easy to write, and that reduced friction for teams adopting and modifying API Blueprint. It was a lot easier for me to say "Hey you're already writng Markdown for your manual docs, but if you do it like this you'll have an actual API description which you can use programatically too, for docs, mocks, testing, and SDK generation!"

Apiary was well respected for offering a solid SaaS product, and was well known for their open-source projects: Dredd and Gavel. These tools offered powerful testing functionality which helped teams ensure their API implementation matched the API description, which was foundational to bringing the API Design-first workflow to REST APIs. This API description-based testing would help point out discrepancies in a test suite instead of having complaints from users.

Sadly what is easier for humans is rarely easier for computers, and whilst API Blueprint's ecosystem of open-source tooling maintainers were doing their best it was legitimitely hard to work with, and the official drafter C++ parser was overwhelmed with issues. Third party parsers in other languages would not support everything. This is in my opinion one of the major contributing factors to OpenAPI winning the API description format wars, but Apiary cleverly hopped on the OpenAPI bandwagon adding support for v3.0 too. Abstraction was always the goal for tooling companies working with any of these formats, and this inspired others to diversify their support too.

Sadly all of this is history now, because Dredd and Gavel have been archived along with all the other open-source code from the Apiary team, and the hosted product will be shuttered in September.

Why is Apiary shutting down?

As is so often the case in API industry, they have been assimilated by a giant corporation that wanted to grab the cool new thing and its users.

Oracle bought Apiary back in 2017, and have been migrating users over to their “Oracle Cloud” offering for years. Paid Apiary plans had been deprecated since 2018, and now finally users are seeing banners on their dashboards telling them Apiary is finally turning off the lights September 9th 2025.

Why did Oracle do this? The same reason SmartBear bought Stoplight, Postman bought Akita, and Atlassian bought Optic.

Money
Users
Relevance
Laziness

Capitalism is a history of big companies eating up small companies, whether that's acquiring to absorb talent, or acqui-firing to get code/data that's interesting or purely to put people out of business, sometimes it's a little of all three.

Oracle has a big nebulous confusing product that nobody wants to use and they bought the cool kid alternative of the time, then seemed to want to do nothing with it and just force people to move over to Oracle Cloud, very much like SmartBear are doing forcing people away from Stoplight and over to API Hub.

Do you really want to use Oracle Cloud?

Oracle Cloud is a large offering similar to Amazon Web Services: there’s a whole lot of stuff to sift through to get to the bit that you want, and all you wanted was API documentation that looked nice with almost no work.

This shouldn’t be so hard, especially as Apiary always focused on simplicity. Now it’s incredibly confusing to figure out where you’re meant to go or what you’re meant to do, and that pisses me off.

It’s impossible to even find out how much it might cost, and you know what they say: if you have to ask, you can’t afford it.

Converting from API Blueprint to OpenAPI

I've been helping API documentation products like Bump.sh prepare for the incoming wave of users finally getting out of Apiary.io before they're forced into Oracle Cloud, and I wanted to make sure there was a good open-source solution to converting API Blueprint to OpenAPI.

There are lots of tools out and about, but trust me they will only do part of the job and leave you very confused about whats wrong. It's been an issue for almost a decade but I've spent most of that decade sorting stuff like this out, so I've made you this script which glues together a few options and corrects the most common mistakes as it goes.

Go take a look at apiblueprint2openapi.

git clone git@github.com:bump-sh-examples/apiblueprint2openapi.git

cd apiblueprint2openapi

cp ~/src/my-project/example-api/latest.apib ./original.apib

Wherever your .apib is, probably in your GitHub repo, grab it and pop it in as orignal.apib because I didn't have time to make a proper CLI wrapper for this. Then run NPM because all of these tools I've cellotaped together are NPM packages.

npm install

npm run convert

The conversion script will fill up the generated/ directory with output from two alternative conversion scripts so you can see which you prefer, and both will get upgrades and corrections.

apib2openapi.yaml - Using NPM module apib2openapi to produce OpenAPI v3.0.
apib2openapi.31.yaml - Upgraded apib2openapi output with openapi-format to produce OpenAPI v3.1 and generally tidied up.
apispecconverter.yaml - Using NPM module apib2openapi to produce OpenAPI v3.0.
apispecconverter.31.yaml - Upgraded apib2openapi output with openapi-format to produce OpenAPI v3.1 and generally tidied up.0.

This is probably a lot to think about so to keep it simple, you probably want to use generated/apispecconverter.31.yaml.

cp generated/apispecconverter.31.yaml ~/src/my-project/example-api/openapi.yaml

Want to see how they look with zero effort involved?

$ npx bump-cli preview generated/apispecconverter.31.yaml

> Your preview is visible at: https://bump.sh/preview/9b563ce6-e1a5-4da6-8f5d-d51ae0b26c1d (Expires at 2025-06-27T17:49:34+02:00)
> * Let's render a preview on Bump.sh... done

How did I upgrade to OpenAPI v3.1?

You gotta learn about OpenAPI Format if you work with OpenAPI. Not only can it upgrade from v3.0 to v3.1, but it can tidy up and refactor your OpenAPI document, improving readability and fixing mistakes.

npm install -g openapi-format

openapi-format openapi.legacy.yaml -o openapi.yaml --convertTo '3.1'

This will output a new OpenAPI document called openapi.yaml which is formatted nicely and upgraded to the latest version.

Tidying up the mess

Anyone who has ever managed a developer portal trying to handle a deluge of disparate quality API descriptions coming in will know that API teams demand the best results despite generally not wanting to do any work to help that happen. Even if they want to play ball, god knows what their pipeline is and how possible that would even be. Could be creating OpenAPI from code annotations. Could be generating from HTTP traffic. Could be AI slop. Could just be a well meaning team inexperienced with OpenAPI.

Learning to programatically uplift OpenAPI is incredibly helpful regardless, and OpenAPI Format does a great job of shaving the edges off.

openapi-format generated/apispecconverter.yaml -o generated/apispecconverter.31.yaml --convertTo '3.1' -c config/openapi-format.json

There is a lot you can do with the config file, but the bare minimum to get the converted API Blueprint output into usable OpenAPI for me meant passing vacuum linting rules, and this did the job.

{
  "sort": true,
  "casingSet": {
    "operationId": "kebab-case",
    "properties": "snake_case"
  },
  "generateSet": {
    "operationIdTemplate": "<method>-<path>",
    "overwriteExisting": true
  }
}

This removed the nasty and invalid operationId entries, and gave calm consistent ones which would match conventions in other APIs nicely. It also sorted things alphabetically and set naming conventions for properties. What an absolute treat.

Iteratively improve OpenAPI

The conversion process is not always perfect, but a larger problem is that API Blueprint didn’t have a lot of the features that OpenAPI has, so you may find that your OpenAPI document is missing some information.

For example, API Blueprint didn’t have a way to describe authentication. That felt like a huge admission at the time, and folks were working on it with API Blueprint RFC 002: Authentication, but seeing as that never got done you’ll likely have to add this all in manually.

OpenAPI v3.1 can describe all sorts of authentication and authorization via Security Schemes, so with a little bit of work you can add this in to your OpenAPI document and get it where it needs to be.

So long Apiary

To the team who made Apiary awesome, thanks for everything you did, and it was a pleasure to meet you all that one time in Prague. I hope you got paid handsomely for all your hard work and they didn't force you to stick around too long.

To Oracle, pffffft.

If you're looking for a new API documentation solution to get away from Oracle, check out our comparison of the Top 5 Best API Documentation Tools.