Apiary: The API documentation tool that will change your API game

There are few tools on the market as complex and advanced as Apiary. It’s a REST API documentation tool (when really, it’s much more than that), which allows you to quickly design an API and share it with whom it might concern using a mock server provided by Oracle. It has a wealth of features, each of which can be very useful on its own. But it shines its brightest when we use its full potential.

When we do we can quickly create and mock our APIs, share them with clients and developers, automize the process of creating highly interactive and very beautiful documentation, and much more. With this article, you will be able to unleash the potential of the APIARY API documentation tool as well. So let’s cut to the chase.

APIARY – how does it work?

At Apiary’s heart is API Blueprint – a high-level description language, which makes designing APIs a breeze. Once our list of requirements is ready, the system will verify our syntax and subsequently launch a mock server, which will respond to our requests. At this point, frontend developers can already start working with it. But our journey with Apiary is only beginning. After all, our API description is a contract that all backend and frontend devs need to adhere to, so we need to commit it to our repository. Apiary’s deep GitHub integration makes it a one-step process. What’s more, thanks to integration with Dredd – a testing framework – backend services will be able to automatically generate tests. All that’s left to do is write code that will pass them all.

Cool. But in order to understand why all this is so useful, we need to take a step back and answer another question.

Why do we need contracts and mock servers?

Frontend and backend developers can’t always work simultaneously – timing is very important.

For example, a frontend dev can’t do its job without mocking endpoints first unless all backend job is done. As a result, one task can often span two, three, or even four sprints. if we could somehow make it so that frontend and backend are entirely independent of each other, the development would be much faster. Let’s see how it can be done without having to create an all-full-stack team.

Once we commit the contract to our repository, we can create our definition of done, since we now know what and where should be achieved. When the contract is verified, Apiary launches a mock server, which means that a frontend dev can start their work. Backend work is easier as well – Apiary can use the contract to generate automated tests for use in Dredd. This framework can help us test the implementation of an API. It’s not quite as sophisticated as Behat, but more than sufficient to generate basic tests for our app to comply with.

And what if a developer breaks the contract? Since we’re using automated tests, we will be informed about it instantly.

Creating an API description with the Apiary documentation tool

Let’s create an API documentation example with Apiary. Making an API description with API Blueprint is quite straightforward. The language itself (Oracle’s own creation) has a low barrier to entry. Bundled with our first project is an example description, which we can freely use. Once you master Apiary, you can try Swagger – a more complex and capable API description language for making REST API docs (using OpenAPI Specification, formerly Swagger Specification) and much more, with very cool features such as Swagger UI. However, unless we need modeling or imports, API Blueprint will suffice.

As you can see, the syntax is reminiscent of Markdown. Above, you can see the description of an /elements endpoint, which response to GET requests. The endpoint will return a collection, which here includes just one object. Apiary will render the endpoint to the right.

What can we find under List All Elements? Could it be that Apiary has something more in store for use?

Indeed. Under this URL you can find an API client, which you can use to test your new endpoint.

As you can see, the mock server returned just what we requested. The frontend dev has all they need now. What about the backend? We’ll soon get to that. But first…

API Inspector

Thanks to the convenient API Inspector, we can see exactly who used our endpoints and what kind of requests were made. This is what the inspector tab looks like:

All elements are clickable. Below, you can see the endpoint test we just made.

This feature is very useful for frontend developers – if their requests do not comply with the contract, they will know that immediately.

OK. At this point, we can rest assured that Apiary will be of use for our frontend friends. What about backend? There are plenty of utilities for them as well, but the one that stands out the most is….

Dredd – simple API testing framework

Dredd is another handy API testing tool from Oracle.

Does that mean that it is yet another Behat? Of course not. Had it not provided anything new, it wouldn’t have been made.

When compared to Behat, Dredd does away with a lot of complexity. Its main goal is to extract the definition of endpoints from the Blueprint file and send them over to our (local) backend. Thanks to that, we can quickly ascertain if the data format the endpoints return meets our requirements. How to do that? It’s quite simple. The “tests” tab includes a short tutorial, which guides us through the process of installing an app and creating basic config files:

Open your terminal, use the “dredd” command, sit back and let the magic begin.

Now we can be sure that our endpoints return data properly. Keep in mind, though, that Dredd does not test the logic of our app. The backend still requires BDD tests.

Back to Dredd, when the test is over, we are given an URL that takes us to the results page. Each completed test has its own separate tab in Apiary so that we can get back to them:

Now we know that our script has tested all endpoints, allowing us to mark the job as done (complaint with the contract).

We sure saved a lot of effort and, by extension, time and money!

Apiary’s selling feature – full GitHub integration

Apiary is integrated with GitHub by default. We can instantly create a new branch out of our new API contract, and then git-commit it and send to GitHub. The entire process takes just a few clicks to complete.

Step 1. Click the “Push” icon at the top right.

Step 2. Enter a commit message.

Step 3. The changes are moved to the master branch of our repo.

Unfortunately, the master branch is the only one we can choose in a free version. To push changes to other branches, a paid plan is required. And it may be worthwhile to go for as it gives us big advantage – with that, our endpoints can fully become a part of our project. We will be able to use version control to know exactly who and when modified the contract. Business-wise, it’s a massive benefit.

Apiary API documentation tool can make both a dev and a client happy

Whether you plan on using all or some of Apiary features such as interactive documentation or designing,  you should find it very useful. To give you an idea, in one of the projects I did, we used Apiary to create a mock version of an external (paid) API, using documentation provided by the vendor. Once the project was out of development, switching to the real deal proved amazingly easy.

One of my colleagues created a contract that included over 60 endpoints. With that, it was possible to integrate half a year’s worth of backend and frontend work within 5 days.

It’s hard to think of a better recommendation for Apiary than this. What’s more, the entry threshold is low enough that you can start your first project as early as today. And backing from a company as big and trustworthy as Oracle means that your project is certainly in good hands.