The Best Tools for Working with API Requests

Adam DuVander
Adam DuVander / January 26, 2017

Imagine yourself as an explorer, braving high sea or rough terrain to discover new routes. Along the way you’ll meet many people, most of whom won’t speak your language. An interpreter would be crucial to your trip, making it possible to communicate and navigate unfamiliar territory.

When building or consuming an API, you need a similar translator to aid in your exploration. I suppose you could have a human perform this translation, but computers do a much better job of making API requests and parsing the responses. Yet, there is still a human element to the exploration phase of an API. During that period, you will want one of these four tools to assist you in working with API requests, to stand in as an interpreter that makes sense of the API.

cURL: Command Line Granddaddy

It would be negligent to write about these tools without starting with cURL. The popular command line utility was created during the booming Web 1.0 years. Today, it's bundled with macOS, runs on Windows and Linux, and is used as a language-agnostic example in the documentation of countless APIs.

Stripe cURL examples

Stripe, for example, has one of the best examples of API documentation and they make wide use of cURL examples. You can simply copy an example request in Stripe’s documentation and paste it into your command line. Stripe makes it easy so developers can quickly get a feel for the API, while recognizing one tiny catch: cURL isn’t particularly easy to use.

There are so many different flags to send along with cURL commands that they’ve almost run out of letters. Further, the software is built to work with more than just API requests. There are a laundry list of protocols and authentication methods in the cURL documentation. It’s a powerful tool, but with great power comes great… complexity.

That said, with a little practice, you’ll memorize the handful of common commands you’ll use most with modern APIs:

  • -H for HTTP headers: -H “Content-type: application/json”
  • -X for HTTP method: -X POST
  • -d for data: -d ‘{“field”: “value”, “numeric”: 42}’
  • -u for basic authentication: -u “username:password”

We’ll send a Zapier shirt to whoever comes up with the best way to remember the HXdu flags, because I could really use a mnemonic.

HTTPie: Intuitive cURL Alternative Made for APIs

Want the command line functionality without the complexity? HTTPie was designed specifically for RESTful APIs, so it makes some assumptions that save time and keystrokes.

HTTPie vs cURL

Since many modern APIs use JSON as a data format, HTTPie expects JSON in requests and when parsing responses. Even better, minified JSON (when unnecessary whitespace is removed) is expanded, indented, and syntax highlighted. It’s easy to read the responses, which means I find myself going through a series of requests much faster with HTTPie.

HTTPie is a joy to use and I’ve seen many people react like Victor. You still have some syntax to memorize, but far fewer flags:

  • HTTP methods and other headers are passed without any flags: http POST
  • Data uses equals signs, with special syntax for non-strings (:=) and data in query strings (==), for example: http POST field=value numeric:=42
  • -a for basic authentication: -a “username:password”

For the most part, the syntax fades into the background, and you’re left with a pure API experience. Form-based Request Inspector

So far, the tools for working with API requests live on the command line. HTTPie and cURL are rugged, for fast and experienced exploration. If you’re after both a translator and a guide for your journey, though, consider the web-based

Here you start off simply: Choose your HTTP method and paste your URL. If you need to add authentication, other headers, or parameter data, click the appropriate buttons. You won’t have to remember flags or other syntax (other than JSON if you’re adding a body to a request). lets you review the request and explore the response as pretty, syntax highlighted, link-clickable JSON. Scroll to the top and make edits–your original form fields remain.

Postman: Chrome Plugin for Larger Projects

If is a guide, then Postman is a Sherpa. The Chrome plugin is also available as native apps for Windows and Mac, giving you a complete API diagnostic tool. Though used by developers consuming an API, Postman’s most powerful features are aimed at API providers.

Postman OAuth call to GitHub

For basic usage, the experience is similar to Choose your HTTP method, paste your URL, and add your other headers or body data. Again, there aren’t command line flags to learn, but that doesn’t mean Postman isn’t powerful. For OAuth-based requests, for example, Postman walks you through the process of retrieving and using a token. Then your token is available for all subsequent requests.

As you use Postman, it logs your previous request history. Further, you can store them as collections, share with others, and import API descriptions (such as Swagger and RAML). And there’s more to be discovered. The Sherpa will present them to you when you’re ready.

Now you’re ready to begin your API exploration. You have a team of four potential translators, ready to bring your API request to a server and return it safely with a response in hand. Who you pick depends on the level of detail you’ll need and how often you expect to need it.

Load Comments...

Comments powered by Disqus