About michelada.io

By joining forces with your team, we can help with your Ruby on Rails
and Javascript work. Or, if it works better for you, we can even become
your team! From e-Commerce to Fintech, for years we have helped turning
our clients’ great ideas into successful business.

Tags

Keep your API in shape with API Blueprint

When you are starting a new API project with Rails your first question might be: should you do it using GraphQL or just go with a good old REST API.

After much consideration, you decide to go with a REST API? Good! Continue reading this post.

Now, before you begin to consider how to implement your API, your main concern should be how to keep your API documentation up to date. This is something that always creates a sort of tension in projects where the team have to go through many hoops to keep code and docs in sync.

In a recent project, I was looking for a solution that could be easily integrated into our Rails application and at the same time allow the team to write the API definition without caring about the implementation details.

The first tool that I found was the rspec_api_documentation gem but it was incompatible with our project for two reasons: We use Minitest and it requires you to write Specs with Ruby code to describe the API.

Then I remember that in a project for one of our clients at michelada we did use Apiary as a communication tool to describe the API implemented there.

API Blueprint

Apiary has an Open Source format called API Blueprint. It is a specification on top of Markdown that helps describe a web API. This format is oriented to creating documentation.

With this specification, you can define how a request should be made and what to expect as a response from an API. Here is a sample fragment of API Blueprint that shows how to document the /questions endpoint, no code just Markdown and a special syntax MSON to document the response.

MSON syntax allow us to describe JSON objects in a very simple way no matter how complicated you JSON object is. An object structure with MSON like the following:

- address
- street
- city
- state

Produces a JSON object like:

{
"address" : {
"street": "",
"city": "",
"state": ""
}
}

The format is fairly simple to get up to speed quickly and write a complete set of API documentation. From the format is also possible to generate JSON Schema draft 4 for us, we can use these schemas to validate our API with Minitest.

Generating good-looking documentation.

Let's start with the low hang fruit of using API Blueprint to document our API. Here is the documentation for two API endpoints that we are going to use in this post as an example.

The API is simple but it shows nice things about the MSON syntax like data structures reuse. It also shows how to document a response that can have many different statuses.

To render an HTML document of our documentation we can use a tool called aglio. It parses the file and generates a nice looking document. You can choose any of the available themes or you can write your own.

In a Rails application, we install aglio with Yarn as follows

$ bin/yarn add aglio

The basic command, given you saved the documentation file in the docs/api folder and want to output the HTML to the /public folder, would be:

Generating JSON Schemas

Now that we have nice looking documentation its time to generate JSON Schemas from the documentation, with these schema files we can use Minitest to automate the verification that our API is responding in the format we expect.

There is a tool called api2bjon that does the extraction of JSON Schemas from API Blueprint documentation. It generates a single JSON file for all schemas present in the documentation.

To generate the file with all schemas first, install apib2json and then execute it.

But as I said before, for this file be useful we need to split it to have each schema in their own file. To accomplish this let's create a rake task. Open the file lib/tasks/api.rake and add the following code:

Executing this task will generate the schemas.json file from the API Blueprint document but it will also split the file into many files, each one containing a schema for a single response. Files will be named with the HTTP Verb, the resource, request name if any, and the HTTP status code for example: GET-Users-200.

The key here is the assertion for a JSON Schema. If your endpoint is not responding with the expected format then you get detailed information from the test telling you what are you missing, what was expected and what was your response.

Conclusion

Keeping your API documentation and endopoints in sync can be a daunting task, writing schema files by hand are not fun at all but hopefully, with the tools presented here it will be easy for you and your team to keep everything up to date.

View Comments

Share Article

About michelada.io

By joining forces with your team, we can help with your Ruby on Rails
and Javascript work. Or, if it works better for you, we can even become
your team! From e-Commerce to Fintech, for years we have helped turning
our clients’ great ideas into successful business.