How to Test APIs in Ruby with Airborne

This installment of the API Testing series will focus on the Ruby Airborne API tester Gem will be of interest to those with a strong inclination towards the Ruby Platform. If you follow along all the steps you'll create an API test running against the Trello API, a real API with formal Authentication tokens.

While there are numerous API testing solutions, the Ruby Airborne API tester Gem will be of interest to those API providers with a strong inclination towards the Ruby platform. If you follow along all the steps, you'll create an API test running against the Trello APITrack this API, a real API with formal authentication tokens. Or you can do the faster version, reading along to get a "feel" if Airborne is something that you'd like to try. A real follow-through requires some set up. You'll need to install the Ruby programming language along with the Airborne Gem, create an account on, and generate an application key and a token to use the Trello API.

Feature Set

A handful of features are mandatory for an API testing Framework — wrappers to make calls easy, assertions or the ability to extend and create them, and chaining or the ability to use part of a response in the next API call. Though discussed elsewhere in this series, you should remember that assertions are tools used to check that some aspect of the response is what you're expecting and chaining is when you store part of a API response in a variable to use later. Airborne can do all of these things.

People that test APIs will want to apply assertions to specific keys in the JSON response, date and data types, headers and header contents, and HTTP status. All of these are built into the framework. You can read about the full set of assertions by looking at request_expectations.rb in the Airborne GitHub repository. Chaining can either be done with the extract_expected_value() method or by assigning variables using the Ruby programming language. This is crucial for products that need to authenticate with a username and password, get a token in the response, and then use that token in the next request. Chaining is also important for data manipulation — create a new Trello board, capture the ID new board, and then use the ID to refer to that board so you can make a change. Airborne is free and open source, so you can extend the Library if there are important features missing.

Here is a simple example of a POST using Airborne:

require 'airborne'

describe 'sample spec' do
  it 'should create a new Trello board' do
post ' HTTPS://,desc&key=<KEY>&token=<TOKEN>', { :name =>
    expect_json_types(name: :string)
    expect_json(name: 'My new Trello board')

This code makes a call to /boards to create a new Trello board called My new Trello board. Three assertions are made after the call is made. One verifies the datatype of a key in the response, another that verifies the data contents of that key, and the last asserts that there is a HTTP 200 response. A more realistic test would perform a full create, update, delete ( CRUD) cycle. Create a new board and assert that the response is what you're expecting, make some changes to the board and make sure that the changes were saved, and then delete the board.

Airborne is designed to be used in conjunction with RSpec. RSpec is a Ruby framework for testing and is used often in development groups that do Behavior Driven Development (BDD). Tests generally follow the RSpec convention like you see in the code example above where you have a group of tests in a describe block and individual tests in a describe/do block. Tests also typically have _spec at the end of the file name.

Ease of Use

Many API tools, such as Ready API and Postman, are built around a User Interface. Testers perform individual calls, create reusable tests and test suites, schedule test runs, and collect, logging all through that one user interface. The UI allows people with no programming experience to approach testing closer to the code, but also tends to separate developers from this aspect of the testing work. Airborne is a programming framework, so it has no user interface other than the text file you're using to create code and the tooling you use to run the tests. That said, it's extremely approachable for people who have never written any code.

A person with no programming experience can probably get up and running with Airborne in a week. Pairing with a developer, especially a Ruby developer who knows RSpec, will shorten that learning curve considerably. The person developing these tests doesn't need to be an expert programmer, as most API tests are relatively simple. Like the example above, a person makes a call to an API, and then looks at some attributes of the response. Testers using Airborne just need to remember a few key methods in the toolset and some Ruby and RSpec basics.

Team Fit

Teams often select tools based on how they imagine the tool will fit within their workflow. Those tools also have a special way of changing the team's workflow. Airborne is a good fit for development teams that want to add a layer of testing at the service layer. The actual tests might be built by developers as part of their defining what it means for a feature to be done. They could also be built by a technical tester that's embedded on the development team, or the tester could extend the basic scaffolding created by the developers. Because this is a programming framework, fitting this into an environment using Continuous Integration or Continuous Delivery is easy. A team could install the Airborne Gem on the build server, and then have the tests run everytime there is a new commit to the API Branch. This workflow makes responding to feedback from failed tests easy for the development team. (My colleague, Matt Heusser, points out that you may want to change the subdomain depending on where the code is tested. This is easy enough to have a default that can be overridden by a command line argument or an environmental variable.)

The Bottom Line

Airborne is a fully featured, extensible library for API testing. This tool is a good fit for software testers who can write a few lines of code at a time, teams using pair programming and collaborative approaches (such as Extreme Programming approaches), or development groups that want to add some repeatable tests to their service layer. Best of all, Airborne is free and open source.

Get testing today, and let us know what you find.

Be sure to read the next Testing article: How to Test APIs From the Command Line With HTTPie and cURL