The Best Tools for Working with API Requests
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, 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.
curl has options on all single letters a-z (upper and lower case), except for TWO upper case letters. We're saving them for... hm, I dunno.
— Daniel Stenberg (@bagder) December 29, 2016
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.
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.
If you are developing RESTful services and haven’t heard of HTTPie? Fix this ASAP: https://t.co/mCIWiHok1m You'll thank me later :)
— Victor Farazdagi (@farazdagi) December 22, 2016
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 http://example.com - Data uses equals signs, with special syntax for non-strings (
:=) and data in query strings (==), for example:http POST http://rexample.com 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.
Hurl.it: 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 Hurl.it.
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).
Hurl.it 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 Hurl.it 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.
For basic usage, the experience is similar to Hurl.it. 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.
Comments powered by Disqus