Spending time and effort to design and build user-friendly APIs is no longer a “nice to have”. APIs should be embraced as a product in their own right. An API should empower the user, internal or external, to explore and understand the data with ease. They should be able to navigate the API without crying out for help from someone actively working on the API. In the same way that user interfaces go through usability testing and feedback cycles, an API should include a similar process to ensure the consumers will actually enjoy using it. After all, they are the reason the API exists.

What makes an API user-friendly? As a start, let’s review the Richardson Maturity Model.

  • Level 0 – Use HTTP/HTTPS as the transport system (yes, I realize this may seem obvious at this point).
  • Level 1 – Break out the API into logical resources rather than grouping things into conglomerate endpoints.
  • Level 2 – Use the HTTP Verbs as they were intended or at the very least be consistent in how you use them.
  • Level 3 – You don’t have to go full on HATEOAS but build an API that is easily discoverable. There should be enough commonality across the API so that someone can learn a few endpoints and start to predict the structure and operations for others.

Achieving these levels of maturity can help a team in creating high-quality APIs, but many APIs go one step further by exposing documentation via an exploration tool such as Swagger or Apiary. Both solutions have their pros and cons, but for the purpose of this post, we will be focusing on Apiary.


Apiary is a proprietary API Design Stack backed by Oracle. It has an online interface and integrates with API Blueprint, a high-level API description language that sits atop Markdown. As of late, it also supports Swagger. This may be enticing if you’ve already invested in marking up your endpoints with Swagger annotations (or written the YAML manually). The way that Apiary can group a collection of APIs into a single interface makes it a great option for an organization with many services and APIs.

Being that Apiary is a proprietary tool, it does have a cost (although there is a free tier as well). Let’s look at why this cost may be worth it.

Design Driven Development

Apiary shines when it comes to design driven development. Without writing a single line of code you can throw together a new API, document it in the online editor, and have a mock server running and ready for feedback. This process can be completed in a matter of minutes. Going a step further, you can hook up the API to a Github repo in just a few clicks. This integration allows for changes to flow between Apiary and your repo seamlessly. The speed and flexibility of spinning up a mock server enables shorter feedback cycles between the business and development. Thinking before coding is an important step to creating high-quality APIs and Apiary alongside API Blueprint can set a team up for success in that regard.

API Blueprint

Many developers are becoming familiar with Markdown syntax due to its adoption by a variety of tools as a documentation language. The fact that Apiary’s description language (API Blueprint) is Markdown makes it familiar and quick to get up and running. Furthermore, API Blueprint is open sourced and recognized as an official language by GitHub.

The example below illustrates documentation for two endpoints. Markdown makes this file easy to read regardless of technical ability. Apiary consumes this file and generates an easy to use API explorer where you can test out the real APIs or a mock server.


Apiary Teams enable you to collaborate with people of various roles, from restricted viewer to an admin editor. The access level can vary across projects or APIs. This is a powerful way to make sure everyone who should be exposed to the API has sufficient access.


API Blueprint continues to gain traction and as a result of this, the tooling options continue to expand. There are a variety of tools that can help with every step of creating an API, from editing the Markdown to testing and continuous integration.

Apiary & API Blueprint Community

Technologies have flaws, this is just the nature of the beast. However, a solid backing community can help alleviate pain points. Apiary and API Blueprint have great documentation and examples to help guide a team in creating an easy to use API explorer. Here are a few links that should help you get up and running with Apiary and API Blueprint.

If you’re looking to test out the platform, the free tier is definitely a sufficient option for a trial run. Good luck!

About the Author

Matt Schroeder profile.

Matt Schroeder

Director, Real-Time Data

A wide range of professional experience and a Master’s Degree in Software Engineering have become the foundation that enables Matt to lead teams to the best solution for every problem.

One thought on “Designing APIs with Apiary & API Blueprint

Leave a Reply

Your email address will not be published.

Related Blog Posts
Building Better Data Visualization Experiences: Part 1 of 2
Through direct experience with data scientists, business analysts, lab technicians, as well as other UX professionals, I have found that we need a better understanding of the people who will be using our data visualization products in order to build them. Creating a product utilizing data with the goal of providing insight is fundamentally different from a typical user-centric web experience, although traditional UX process methods can help.
Kafka Schema Evolution With Java Spring Boot and Protobuf
In this blog I will be demonstrating Kafka schema evolution with Java, Spring Boot and Protobuf.  This app is for tutorial purposes, so there will be instances where a refactor could happen. I tried to […]
Redis Bitmaps: Storing state in small places
Redis is a popular open source in-memory data store that supports all kinds of abstract data structures. In this post and in an accompanying example Java project, I am going to explore two great use […]
Let’s build a WordPress & Kernel updated AMI with Packer
First, let’s start with What is an AMI? An Amazon Machine Image (AMI) is a master image for the creation of virtual servers in an AWS environment. The machine images are like templates that are configured with […]