---
title: Document an API with Paw
teaser: 'Make it easy to figure out your APIs with live documentation.

  '
tags: web,api,http
author: Jason Draper
published_on: 2015-03-23
---

Have you ever worked with an API
that provided insufficient documentation or
none at all?
It is really painful!
If you're trying to write an interface against the API,
it is like coding in the dark:
you just throw things at the API
and hope for a proper response.

In an ideal scenario,
you could update the documentation,
either by submitting a pull request
or sending an email,
but those factors are often out of our control.
Even if you have a well-documented API,
you still need to try requests against the API
to make sure you understand how it works.
I've used a number of tools for this
including curl,
small scripts
and GUI editors.

Recently,
I started using [Paw] to work with APIs
and found that it has been really helpful to our process.
I'll talk about a few of the benefits
but first let me quickly explain what Paw does.

## What is Paw?

[Paw] is a Mac application ($29)
that provides an interface
for sending web requests to an API.
It is primarily designed around REST APIs
and provides a very easy way to manipulate the arguments,
headers,
and others part of your request.

Paw saves your queries
and allows you to name
and group them.
The queries are stored
in an application-specific file format
that can easily be shared
with other Paw users.
All this is wrapped up
in a very intuitive and helpful GUI.

![Paw Screenshot](https://images.thoughtbot.com/paw-for-api-documentation/paw_screenshot.png)

## Living Documentation

On a previous project,
I was tasked with building an EmberJS application
against an API that I did not control,
without access to the source,
and the API was not properly documented.
My only hope at finding out what options were available
was to bug people who had worked with the API
and continue to toss queries at it.

I used Paw to make my life easier:
it helped me to have executable documentation
I could easily update and keep on hand.
I could play with queries,
make sure they were properly formed,
check the return values,
and save them in my collection
in case I needed to change something in the future.
The process of quickly adding an extra argument in Paw
and then verifying the result
was very helpful
and sped up a lot of my testing.

Paw also supports [plugins]
which allow you to export generated code
for specific languages
or export API documentation in different formats,
such as Markdown.

## Onboarding New Developers

Paw turned out to be a really nice way
to hand off my knowledge
to the next developer on the project.
Though most of the main API endpoints
were already used in the application,
having a Paw file with examples of all the options
made it very easy for the new developer
to see what was available.

Having the Paw file available
also made it very easy
to troubleshoot problems
in our application.
We could easily throw the query into Paw
and find out if the problem was with our app,
our understanding of the API
or the API itself.
By leaving that knowledge in the Paw file,
we've saved future developers
from having to go through a similar process.

## Downsides

Paw is Mac only,
which is not ideal.
We have teammates
who are not Mac users
and they will not get the same benefits
from the legwork we've done through Paw.
There are a few cross platform options out there,
including Chrome extensions,
but so far,
I haven't found any that match the level of polish that Paw provides.

Paw may not be right for all teams
but if your team is primarily on OS X,
I highly recommend trying it out.
If Paw is not an option,
a small script
that has saved commands
for all the endpoints
may be a great compromise.
The goal is to store
as little knowledge about the app in our heads as possible
and put more of it in the documentation
or codebase.

[Paw]: https://luckymarmot.com/paw
[plugins]: https://luckymarmot.com/paw/extensions/