Architecture & DesignIntroduction to Apiary: Overview of Apiary and How to Create APIs

Introduction to Apiary: Overview of Apiary and How to Create APIs content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.


The Application Programming Interface (API) has operations that can be consumed by the application. Let’s understand with the help of a scenario where APIs play a role. Say there is a taxi company that wants to allow booking of a taxi through a mobile app or a web site. Now, this feature or operation needs to be exposed so that it can be used by clients that are developing the web sites or a mobile application. The operation to expose the cab booking will have some input and output parameters. These operations are a contract between the people creating the API and people consuming the API.

In this article, we will see how Apiary plays a role in API design.


Here, we will see how Apiary can help design APIs quickly and how it can help overcome some common implementation and integration issues.

What Is Apiary?

Apiary allows us to first create the design of an API and then implement it. Apiary helps in creating a mock API framework and also generate its documentation fairly quickly. In the API design, we specify the supported operations, the input parameters for the operations, and also the output data model; in other words, JSON output. These mock APIs can be consumed in the applications to see if the API design meets the application needs. With Apiary, the modifications can be quickly modified and can go through a number of iterations very quickly without writing any code.

Why Apiary?

Generally, if we wish to create an API, we first define the schema for the input and the output. Then, we define the operations to return the data; in other words, we implement a minimal solution before it can be integrated.

With Apiary, APIs can be designed (or declared) where the input and the output data can be mocked. Mocked data represents the output the action will return. This mocked API and the data can be integrated and tested to verify that it meets the application requirements. These changes can be made without any coding effort.

This also helps when there are multiple teams working simultaneously. One team works on API implementation and other teams consume the APIs. Once the contract is finalized, both the teams can work independently.

How to Use Apiary

To use Apiary to design APIs, click ‘Apiary‘. Use your GitHub account to start API design. Once logged in, the UI gives an option to create a new API. Specify a name and click the “Create API” button. It creates the mock API methods; for example, to lists notes, to create notes, retrieve a node by ID, and so forth. It also specifies the different HTTP methods being used; in other words, GET, POST, DELETE, and so on.

Let’s understand the different sections of the API declaration.

 1. FORMAT: 2A
 2. # testAPI
 3. Notes API is a *short texts saving* service similar
    to its physical paper presence on your table.
 4. # Group Notes
 5. Notes related resources of the **Notes API**
 6. ## Notes Collection [/notes]
 7. ### List all Notes [GET]
 8. + Response 200 (application/json)
 9.    [{
10.       "id": 1, "title": "Jogging in park"
11.    }, {
12.       "id": 2, "title":
          "Pick-up posters from post-office"
13.    }]

A sample API, as declared in the preceding code snippet, displays the documentation output as shown in Figure 1.

Figure 1: Output from the previous API

  • Line 1: FORMAT specifies the version of the API.
  • Line 2: In #testAPI, ‘#’ defines the heading in the documentation. The number of # symbols defines the sub headings; in other words, ## & ### on line 6 & 7 defines the sub headings.
  • Line 4: # Group Notes defines a group named ‘Notes’.
  • Line 6 defines the sub heading and the URL to access the API.
  • Line 7 specifies the HTTP method and the action name. In this case, the HTTP method is ‘GET’ and the action name is ‘Notes’.
  • Line 8 specifies that the action returns a response status code as 200 and the JSON data.

This explains how the mock APIs return data. The screen in Figure 1 displays the documentation created for the API design.

It also supports other verbs like ‘POST’ & ‘DELETE’. An example for the ‘POST’ is:

1. ### Create a Note [POST]
2. + Request (application/json)
3. { "title": "Buy cheese and bread for
   breakfast." }
4. + Response 201 (application/json)
5. { "id": 3, "title": "Buy cheese and
   bread for breakfast." }

At Line 1, the HTTP method “POST” is defined. In this example, it take an request parameter named ‘title’ and returns a response code 201 and JSON data comprised of id and title.


With Apiary, the “design API first” approach can be implemented where the input/output parameters can be finalized and the mock ups can be tested even before it is implemented. This will improve the coordination between teams and also productivity.


Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories