DEV Community

Cover image for Keep your API in shape with API Blueprint
Mario Alberto Chávez
Mario Alberto Chávez

Posted on • Originally published at mariochavez.io

Keep your API in shape with API Blueprint

#api #rest #ruby #rails

When you start a new API project with Rails, your first question might be, "should I do it using GraphQL or go with good old REST API?"

After much consideration, if you decide to go with a REST API, continue reading this post.

Now, before you begin to consider how to implement your API, your primary concern should be how to keep your API documentation up to date.

It is not an easy task for the development team to keep code in sync with documentation without going thru many hoops.

At a recent project, I was looking for a solution that could easily integrate with Rails and, at the same time, allows the team to document the API definition without considerations 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, Apiary was used as a communication tool to describe the API with the team.

API Blueprint

Alt Text

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

FORMAT: 1A
HOST: http://polls.apiblueprint.org/
# Sample API
Polls is a simple API allowing consumers to view polls and vote in them.
## Questions Collection [/questions]
### List All Questions [GET]
+ Response 200 (application/json)
        [
            {
                "question": "Favourite programming language?",
                "published_at": "2015-08-05T08:40:51.620Z",
                "choices": [
                    {
                        "choice": "Swift",
                        "votes": 2048
                    }, {
                        "choice": "Python",
                        "votes": 1024
                    }, {
                        "choice": "Objective-C",
                        "votes": 512
                    }, {
                        "choice": "Ruby",
                        "votes": 256
                    }
                ]
            }
        ]
Enter fullscreen mode Exit fullscreen mode

With this specification, you can define how the API receives a request and what to expect as a response. The following example shows how Markdown and a special syntax MSON works together to document an API endpoint. No implementation details are present.

MSON syntax allows you to describe JSON objects easily no matter how complicated your JSON object is. An object structure with MSON like the following:

- address
    - street
    - city
    - state
Enter fullscreen mode Exit fullscreen mode

Produces a JSON object like:

{
    "address" : {
        "street": "",
        "city": "",
        "state": ""
    }
}
Enter fullscreen mode Exit fullscreen mode

The format is relatively simple to get up to speed quickly and write a complete set of API documentation. With the API Blueprint format is also possible to generate JSON Schema draft 4 from it. The schemas are useful to validate your API using Minitest.

Generate 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; they are our example for the rest of this post.

The API is simple, but it shows some benefits of MSON syntax, like the ability to reuse data structures. It also shows how to document a response that can have many different statuses.

Aglio is a tool that uses the API Blueprint format to render good-looking documentation from it. It has a few available themes that you can choose from, or even better; you can write your own.

In a Rails application, to install aglio use Yarn.

$ bin/yarn add aglio
Enter fullscreen mode Exit fullscreen mode

Aglio command needs at least two parameters, the input, where is the documentation file written with API Blueprint, and the output file for the HTML documentation.

$ bin/yarn run aglio -i docs/api/documentation.md -o public/documentation.html
Enter fullscreen mode Exit fullscreen mode

It produces the HTML documentation with aglio’s default theme. You can pass a set of --theme flags to choose a theme, color scheme, layout, and a few things more, check aglio’s documentation for details.

Start your Rails server and point your browser to http://localhost:3000/documentation.html. There you have a nicely documented API.

Alt Text

It is handy to have a rake task to refresh the HTML documentation anytime with the command bin/rails api:documentation. Create a file lib/tasks/api.rake and add the following lines:

namespace :api do
  desc 'Build API documentation'
  task :documentation do
    input_file = 'docs/api/documentation.md'
    output_file = 'public/documentation.html'
    system(" bin/yarn run aglio -i #{input_file}  -o #{output_file}")
  end
end
Enter fullscreen mode Exit fullscreen mode

Generating JSON Schemas

Now that you have nice looking documentation, it is time to generate JSON Schemas from the same documentation file. The generated files, along with Minitest, help us to automate the verification that the server requests/response work as expected.

To generate the schema files from the API Blueprint file, we need a tool called apib2json. It produces a single JSON file for all schemas present in the documentation, this is fine. Still, for our needs, a single file does not work, so we need an additional step to split this file into multiple files, each one with a single schema representation.

Unfortunately, the way that apib2json works, it does not provide enough metadata to help us identify each generated schema to put it into a file. So you need a custom version of apib2json, which you can find at https://github.com/mariochavez/apib2json/tree/additional-metadata.

To install it, use Yarn.

$ bin/yarn add "https://github.com/mariochavez/apib2json.git#additional-metadata"
Enter fullscreen mode Exit fullscreen mode

Then execute it to generate a single schema file. The command needs an input, which is the API Blueprint file, and an output file for the JSON schemas; the --pretty flag is for us to get a human-readable file.

$ bin/yarn run apib2json --pretty -i docs/api/documentation.md  -o test/support/schemas/schemas.json

{
  "[GET]/users{?cursor}": [
    {
      "meta": {
        "type": "response",
        "title": ""
      },
      "schema": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string",
                  "description": "User's email."
...
Enter fullscreen mode Exit fullscreen mode

With the help of a second rake task, the generated file is divided into multiple files; each file will contain one request with a single response. A file GET-Users-200.json contains a request with a GET to Users endpoint with a 200 status response.

Create the file lib/tasks/api.rake and add the following code.

desc "Generate JSON schemas"
  task :schemas do
    schemas_path = "test/support/schemas"
    input_file = "docs/api/documentation.md"
    output_file = "test/support/schemas/schemas.json"
    puts "Generating api schemas from #{input_file}"
    system("bin/yarn run apib2json --pretty -i #{input_file} -o #{output_file}")
    if File.exist?(output_file)
      file_path = Pathname.new(output_file)
      JSON.parse(file_path.read).each_pair do |group, actions|
        actions.each do |action|
          next if action.dig("meta", "type") != "response"
          verb = group.scan(/\[(.*)\]/).flatten.first
          name = "#{verb}-#{I18n.transliterate(action.dig('meta', 'group'))}(#{action.dig('meta', 'statusCode')})#{action.dig('meta', 'title')&.gsub(/ /, '-')}".
            sub(/\{.*\}/, "").gsub(/\(|\)/, "-").gsub(/^-|-$/, "")
          puts "Writing #{name}"
          File.open("#{schemas_path}/#{name}.json", "w") { |file| file.write(action.dig("schema").to_json) }
        end
      end
    end
    puts "Schemas are ready at #{schemas_path}"
  end
Enter fullscreen mode Exit fullscreen mode

To execute the rake task, run the following command.

$ bin/rails api:schemas
Generating api schemas from docs/api/documentation.md
yarn run v1.7.0
$ node_modules/.bin/apib2json --pretty -i docs/api/documentation.md -o test/support/schemas/schemas.json
Done in 0.31s.
Writing GET-Users-200
Writing POST-Users-201
Writing POST-Users-422
Schemas are ready at test/support/schemas
Enter fullscreen mode Exit fullscreen mode

There you have it, one JSON schema file per request/response. The rest is quite simple, add the json_matchers gem in your Gemfile and configure the test_helper.rb to load the gem.

require 'json_matchers/minitest/assertions'
JsonMatchers.schema_root = 'test/support/schemas'
Minitest::Test.send(:include, JsonMatchers::Minitest::Assertions)
Enter fullscreen mode Exit fullscreen mode

Then create an integration test for a UsersController and add the following tests. Each test will perform a request to the API and match the response accordingly to what you documented in the API Blueprint file.

require 'test_helper'
class UsersApiTest < ActionDispatch::IntegrationTest
  test 'Users List' do
    get '/users', headers: { Accept: 'application/vnd.api-test.v1+json' }
    assert_response :success
    assert_matches_json_schema response, 'GET-Users-200'
  end
  test 'Create new User successfully' do
    post '/users', headers: { Accept: 'application/vnd.api-test.v1+json' }, params: user_payload
    assert_response :created
    assert_matches_json_schema response, 'POST-Users-201'
  end
  test 'Fails to create new User' do
    post '/users', headers: { Accept: 'application/vnd.api-test.v1+json' },
                   params: user_payload(email: nil, first_name: nil)
    assert_response :unprocessable_entity
    assert_matches_json_schema response, 'POST-Users-422'
  end
  def user_payload(attrs = {})
    {
      email: 'user@mail.com',
      first_name: 'Jane',
      last_name: 'Doe'
    }.merge(attrs)
  end
end
Enter fullscreen mode Exit fullscreen mode

If there is a mismatch between the request and the documented response, the test will fail with detailed information on why the response differs from the JSON schema.

: failed schema : "links" wasn't supplied. 


expected

to match schema "POST-Users-201": 

{

  "$schema": "http://json-schema.org/draft-04/schema",

  "type": "object",

  "properties": {

    "data": {

      "type": "array",

      "items": { ... }, 

    },

  },

}
Enter fullscreen mode Exit fullscreen mode




Conclusion

Keeping your API documentation and endpoints 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.

If you want to check a sample application with everything showed in this post to go https://gitlab.com/mariochavez/testing-api-blueprint/tree/master.

Top comments (1)

Collapse
 
ben profile image
Ben Halpern •

Cool, I'd never heard of this!

Read next

msnmongare profile image

M-Pesa Express (STK Push) API Guide

Sospeter Mong'are -

msnmongare profile image

The 6 Best Free Tools for Testing Webhook and Callback URLs

Sospeter Mong'are -

yegorov profile image

How to continue to use Rails.application.secrets in Rails >= 7.2

Artem Yegorov -

turingvangisms profile image

Nextjs API Router

Turing -