API blueprint is a powerful high-level API design language for web APIs. In this tutorial, we want to dive deeper into it and learn more about how it works, the differences between API blueprint and Swagger, and what makes it unique that leads to its extensive use. But before we dig into API Blueprint, we must ensure a solid base of information about the “API first approach” concepts.
Table of Contents
- API-First Approach
- What is an API description language?
- What is API Blueprint?
- API Blueprint VS Swagger
- API Blueprint Implementation
- Summary
- FAQ
API-First Approach
One of the many software developments approaches is the “API-First Approach”. API-First Approach indicates that we must treat our APIs as “first-class citizens” and build our whole project based upon them. In this method, we must first clarify our project’s general behavior, such as gathering data from clients, processing them, and displaying them on different devices. For developing a project with the mentioned details, we need to have solid, reusable, and consistent APIs to respond to the clients. This approach has a lot of benefits as we are going to mention some of them below:
- We are reducing the cost of developing the software and also maintaining the project in the future.
- More flexibility to our business as developers and stakeholders have implemented the project’s logic together.
- More scalable systems to grow
- We can develop our project at a higher pace, leading our product to reach the market sooner.
Therefore, it would be best to consider using an API description language to establish a contract for how the API is supposed to behave. Here, tools like Swagger and API Blueprint are coming in handy.
What is an API description language?
API description languages are DSL (domain-specific languages), and they are both human-readable and machine-readable languages, much like programming languages. We use these kinds of languages for describing our APIs for both developers and machines. It is indeed excellent documentation for our software as well. In addition, API description languages have a well-defined syntax, making it possible to process them automatically. Unlike programming languages or API implementation languages, API description languages use a higher level of abstraction and a declarative paradigm, leading to express the “what” instead of the “how”. We can use tools like API Blueprint or Swagger to describe our APIs and then implement our product.
What is API Blueprint?
The official website describes API Blueprint as the following:
A powerful high-level API design language for web APIs.
Here we want to learn more about it.
With the help of API Blueprint, we can achieve our goal, which is building a product with the API-first approach. We can quickly prototype and describe our APIs with API Blueprint’s concise yet expressive syntax. It also allows us to create models for the APIs that have been developed and deployed.
Since the API Blueprint is an API Description Language, it makes developers’ and stakeholders’ lives easier by creating a space for them to collaborate easily and help each other manufacture and edit the APIs much faster and more accurately. Better APIs lead to happier customers, and that indeed is the primary goal of every business.
The API Blueprint has a complete set of tools to work. Some of them are:
| Tool | Examples |
|---|---|
| Editors | Such as Apiary, sublime, atom and so on |
| Testing | Such as Dredd, RSpec API Blueprint, CCLRequestReplay, and so on |
| Parsers | Such as Drafter, Protagonist, Snowboard, and so on |
| Mock Servers | Such as Drakov, API-Mock, API Blueprint Mock Server, and so on |
| Renderers | Such as Snowboard, Agilo, Blueprint docify, and so on |
| Converters | Such as Blueman, Postman2apiary, Apiary2postman, Swagger2blueprint, and so on |
| Lexers | Such as Pygments-apiblueprint and Rouge |
You can find and learn more about each unique tool on the official documentation here.
API Blueprint VS Swagger
According to the Swagger official documentation, we can find the following as the description of Swagger.
Swagger allows you to describe the structure of your APIs so that machines can read them.
Pretty much the same with API Blueprint, isn’t it? Well, not. Swagger & API Blueprint both serve the same goal: better and more straightforward implementation of the API-First Approach. However, there are slight differences between them.
The primary difference between them is that, unlike API Blueprint (which uses Markdown/MSON), Swagger uses YAML/JSON. Swagger focused more on designing, developing, and testing APIs rather than documenting the APIs. Do not worry about writing an enormous amount of code either, and you can generate them with the mock service tool. Swagger is open source, and the Open API Initiative governs its specification.
API Blueprint is also open-source, but it focuses primarily on writing excellent documents for your applications. You can use Apiary to set up mocked services and Github integration, which is a paid service.
So which one should you decide on for your project? Choosing between Swagger and API Blueprint mainly deepened the taste of the team or the limitation of tools for the sake of the project. If you are new to the API Description world, I recommend choosing API Blueprint to begin with the API-First Approach. It helps you gain a better mindset of the API description world, and it benefits you to learn concepts like documenting an application and REST concepts deeply. It is also easy to use since it uses MSON.
Now that we have established some ground knowledge about API Blueprint, let’s see how we can work with API Blueprint in action.
API Blueprint Implementation
To start writing API Blueprint documentation, create a folder on your hard disk. Then, in the root directory of the folder, create a file with the extension of .apib. This extension indicates that the file is an API Blueprint file.
First, we need to specify the API Name and metadata as the following:
API Name and Metadata
FORMAT: 1A
# users
users is a simple API for viewing a list of users, creating a new one, updating an existing user, or deleting a user.
Every API Blueprint file starts with a metadata section. Metadata is a Key-value pair separated by a colon (:)—one pair per line. As soon as the first Markdown element is not a key-value pair, the metadata ends. For example, in the above code snippet, we have indicated that the version of our API is 1.
The next part is #users. Since it is the first expression that is not metadata, we will call it API Name, and after that, we will describe it in a few words like the one in the snippet. Note that we can split the description into as many headings as we want as long as we do not interfere with other building blocks of API Blueprint.
Before moving on to the next step, we must make sure that we are entirely familiar with some core concepts of REST APIs. So let’s take a look at the following image:
The above image indicates all the building blocks of a URL and now that we have taken a look at it, let’s continue the API Blueprint implementation by creating a Group.
Resource Groups, Resource and Actions
With the Group heading, we define a group of resources that are related to each other. This group is known as Path in Rest.
# Group Users
Resources related to users in the API. Getting Users, updating and so on
Within the Users resource group, we have a resource called “User Collection”. We use this resource to get a list of all the users we have. The heading specifies the URI used to access the help inside square brackets at the end of the heading.
## Users Collection [/users]
In REST terminology, we use the phrase Verb for our actions on a resource, such as GET, POST, PUT, DELETE, etc. Here we have the Action keyword specified with a sub-heading inside a resource with the name of the action followed by the HTTP method.
### List All Users [GET]
All the Actions should include at least one response consisting of a status code and sometimes a body. A Response is a list item created by preceding list items with either a +, * or — Within an action. Here is an example of a response with a status code of 200 and a list of users:
+ Response 200 (application/json)
[
{
"firstName": "Hossein",
"lastName": "Mousavi",
"age": 24,
"id": 1,
},
{
"firstName": "Anders",
"lastName": "Hejlsberg",
"age": 60,
"id": 2,
},
{
"firstName": "Brendan",
"lastName": "Eich",
"age": 60,
"id": 3,
},
]
As you can see, the response’s header is also determined, and there is no need to write down Content-Type explicitly.
Sending A POST Request
We use a POST request to send data to a server to create a resource. The data is available in the body of the request. Let’s check how we can do it with API Blueprint:
### Create a New User [POST]
You may create your user using this action. It takes a JSON object
containing a firstName, lastName and age.
+ firstName (string) - First Name
+ lastName (string) - Last Name
+ age (number) - Age
The body accepts a JSON like the following:
+ Request (application/json)
{
"firstName": "Bjarne",
"lastName": "Stroustrup",
"age": 70,
}
A successful POST request returns a response with 201 as its status code:
+ Response 201 (application/json)
+ Headers
Location: /users/4
+ Body
{
"firstName": "Bjarne",
"lastName": "Stroustrup",
"age": 70,
"id": 4,
}
Getting a specific user with its ID
For this purpose, we usually use a GET request, and at the end of the resource part of the URL, we add the user’s ID like the diagram below:
Implementing this is not much different from a regular GET request. However, we need to add something at the end of our actions:
## Users [/users/{user_id}]
Deleting a User
After a successful DELETE request, the resource should return a response with a status code of 204
### Delete [DELETE]
+ Response 204
Summary
API Blueprint, alongside Swagger, is an excellent tool for helping developers to adhere API-First Approach. It eases developers to have a healthy collaboration with managers and gather all the necessary information about the product and its business logic at a high pace. In the long-term, developers can reduce the number of meetings using these tools as they have gathered all the information to process them and write high-quality documentation to refer to in the future. API Blueprint uses MSON (Markdown) language to work, and its files have .apib extensions. We usually have metadata at the beginning. Then, with the help of MSON with different heading titles, we indicate our desires and needs by creating group resources, groups, actions, etc.
FAQ
What language does API Blueprint use?
The API Blueprint powers by markdown (MSON) and uses its heading tags.
What are the primary powers of API Blueprint?
First, it provides us with excellent documentation. It helps developers have a better mindset for developing and growing the application, and we have also wrapped the whole project in a schema for better development in the future.
Is API Blueprint Open Source?
Yes, it is open-source, whilst it has some tools that require a business licence as well.
What is the central concept of the API-First approach?
The main idea is that we first need to prepare our APIs prototypes based on our business logic and then implement the other building blocks of the application based on our APIs.
