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
Natively Compiled Java on Google App Engine
Google App Engine is a platform-as-a-service product that is marketed as a way to get your applications into the cloud without necessarily knowing all of the infrastructure bits and pieces to do so. Google App […]
Building Better Data Visualization Experiences: Part 2 of 2
If you don't have a Ph.D. in data science, the raw data might be difficult to comprehend. This is where data visualization comes in.
Unleashing Feature Flags onto Kafka Consumers
Feature flags are a tool to strategically enable or disable functionality at runtime. They are often used to drive different user experiences but can also be useful in real-time data systems. In this post, we’ll […]
A security model for developers
Software security is more important than ever, but developing secure applications is more confusing than ever. TLS, mTLS, RBAC, SAML, OAUTH, OWASP, GDPR, SASL, RSA, JWT, cookie, attack vector, DDoS, firewall, VPN, security groups, exploit, […]