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

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.

FORMAT: 1A
HOST: http://farmanimals.apiblueprint.org/

# Animals API

Animals is a simple API allowing consumers to view information about the animals on a farm.

## Animals Collection [/animals{?type}]

### List All Animals [GET]

Retrieve a list of all farm animals. Provide a type filter to pull out only animals of that type.

+ Response 200 (application/json)

        [
            {
                "id": "1",
                "type": "Pig",
                "birth-date": "2015-08-05T08:40:51.620Z",
                "name": "Pinky"
            },
            {
                "id": "6",
                "type": "Duck",
                "birth-date": "2016-08-05T08:40:51.620Z",
                "name": "Donald"
            }
        ]

### Create a New Animal [POST]

You may create your own animal using this action. It takes a JSON
object containing an animal.

+ Request (application/json)

        {
            "type": "Pig",
            "birth-date": "2017-04-05T08:40:51.620Z",
            "name": "Alphy"
        }

+ Response 201 (application/json)

    + Headers

            Location: /animals/6

    + Body

            {
                "id": "6",
                "type": "Pig",
                "birth-date": "2017-04-05T08:40:51.620Z",
                "name": "Alphy"
            }

Teams

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.

Tooling

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.

• How to Build an API
• API Blueprint Tutorial
• API Blueprint Examples
• Tools for API Blueprint
• Apiary Blog

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