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.
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.
