TaskRabbit is Hiring!

We’re a tight-knit team that’s passionate about building a solution that helps people by maximizing their time, talent and skills. We are actively hiring for our Engineering and Design teams. Click To Learn more

Jean-Richard Lai

Documenting an API by testing

@ 21 Nov 2015

ruby testing rspec rails documentation api


At TaskRabbit, we are providing an API to our Mobile and Web clients. As an efficient Agile Team, we are moving fast and new features can be shipped and/or updated daily.

An advantage of our environment is that we do not have random clients that consume our API and have a limited number of internal or partner clients.

Another strength is that our team works closely together. This allows us to be more lenient than we would be in other environments when dealing with API changes.

When the product needs a change in the API, the followed guideline is that the the following updates won’t require an API version bump:

  • Adding a simple property in the response (an attribute from a table, a translation, cached data).
  • Allowing an extra HTTP parameter from the client.
  • Removing a property that was never used by a client.
  • Removing a property from a client that is fully deprecated (app will force you to update).
  • API backend refactoring/change that does not modify the response.

However, this methodology requires rigorous testing and documentation. To help us out, we created the tests_doc gem. It allows us to ensure our request’s tests create the right response and to share API responses quickly with the clients. It also helps to keep track of unwanted changes.

It does this by recording selected requests in our test suite to file. By checking in these files and tracking their changes, the whole team gets better visibility into the state of the APIs.

To record an api interaction a minimal change in your test is required:

recording_api_interaction do
  get users_path(popular: true)
  expect(response_body.count).to eq(2)
  # other expectations
  expect(response.status).to be(200)
end

This will generate a users.md file. For more information about the options and configuration, go to the tests_doc github page.

Example Output.

Comments

Coments Loading...