Quickstart guide for using API Blueprint

Author Luka Bubalo
Category Development
Date Aug 22, 2019
2 min read

In this small guide we’ll go through a couple of basic elements of API Blueprint and writing API documentation in the blueprint format.

For this guide, I’ll be using Aglio which is an API blueprint renderer. If you go to apiblueprint.org, you can check out some other tools you can use.

Let’s get started

OK, there’s one thing we need to do before we start – we need to define a resource (User). We’ll be using it as an example that has endpoints for register and login. Our first step is to go through basic syntax for writing documentation, and then I’ll show you what all of this looks like after we put it together.

How to define resources and routes

To define a resource, we need to use a single hashtag – #. For example: # User Group. It’s that simple.

We also need to define an endpoint route for registration – let’s say /register. We do this by using a double hashtag ## for naming and box brackets [] for naming a particular endpoint route. This could look like: ## Registration [/register].

Now that we covered defining resources and routes, let’s continue.

How to define request and response with attributes

To define a specific request, we first need to define its type. Registration request would be obviously POST request. In order to define a request, we need to use the triple hashtag sign ###, and we use the space between [] to define its type and route. After we’ve done all of that, we end up with something  like this: ### Registration [POST /register]

We know the basics, now let’s define request attributes and its types. You do it like this:

+ Request (application/json)

     + Attributes

          + username: `JohnD` (string, required)
          + email: `john.doe@example.com` (string, required)
          + years: 38 (number)
          + password: `mySecret` (string, required)

And now we’re ready to define a response. We do it by doing this:

+ Response 201 (application/json)

     + Attributes

          + token: `aabbccdd1234` (string) - access token
          + user (User)

As you can see, you can easily specify types for a particular attribute. We have some primitive types like string, number and boolean, but we can also use structure types like array, enum and object.

Another thing you can make are your own objects which will be used as types.

# Data Structure
## User
+ id: 1245 (number)
+ userId: 1 (number)
+ comments: (array[UserComment])

Rendering an API blueprint into html

The last thing we’ll cover in this quick guide is rendering an API blueprint into html, and this one is quite simple. If you’re using Aglio, rendering a blueprint into html is as easy as aglio -i input.apib -o output.html.

And that’s it – now you know the basics of API Blueprint.

We’re available for partnerships and open for new projects. If you have an idea you’d like to discuss, share it with our team!

Subscribe to our newsletter

Subscribe now and get our top news once a month.

100% development, design & strategy.

100% spam-free.

You're now a part of our club!

We got your e-mail address and you'll get our next newsletter!