As devs we often need to quickly check a server ala “Is this thing on?”, or “What does that API’s response look like?”. For most folks these days, an application like Insomnia or httpie is the tool of choice for testing API endpoints. I definitely think GUI apps like that make complex parsing and batch-testing API interactions waaaaay easier. But for quick checks, I go all “old sk00l” and prefer the now unloved terminal curl command. This “client for URLs” defaults to GET requests and is a time-saver worth the knowing.

As a legacy terminal command, of course curl lacks any and all polish, but the good news is that curl is already on on pretty much EVERY MacOS/linux/*nix* system in the world. curl was the tool that devs have used in order to do URL/API testing. As a result, there are a ton of curl modifier arguments/flags (all of which are annoyingly CaSe SeNsItIvE), because this utility/command was designed to do pretty much everything one could think of. With so many options for adding in data files, cookies, authentication, user-agents, and more, you may end up with some rediculous sequence of arguments. So YMMV, but like I said, I’m going for quick utility and brevity - there aren’t that many flags I actually use and most have long and short versions where I’ll prefer the latter.

1. Make a GET Request:

curl http://localhost:3000/api/ = A basic one shot GET request, in this case to a localhost http-server at port 3000. That’s all there is to it.

A few modifier flags

• -v [-verbose] - Shows everything that happens in the request: IP addresses, connections status, headers, etc…
• -# [–progress-bar] - Displays a visual progress bar which is useful if things seem to be timing-out. For most requests it’s usually gone so fast, you don’t even see it.
• -i - include request headers in the response output. (As opposed to -I which means only show the response headers.)

2. Testing POST Requests:

POST without any data

• -X is short for --request(🤔whut?🤷), and allows you to specify which type of request you want to use - GET, POST, PUT, or DELETE
• curl -X POST http://localhost:3000/post-endpoint/ tells curl to use a POST method, but this doesn’t send any data.

POST with URL-Parameter Data:

Using -d (short for --data) will automagically flip curl from GET to POST. You write the URL parameters in quotes before the endpoint URL:

curl -d "name=Rich&key=val" http://api/postendpoint

Truthfully, I always end up including -X POST before the -d, but that’s just a habit. Important thing to remember is that the default behavior of curl is to send data with a form-urlencoded header¹, so just like an HTML-Form’s POST data, your string must be URL-Encoded - aka, turn all the spaces into %20!

POST with data from a [text] file:

To specify data from key/values as written in a text file, you still use -d, but instead of writing the actual data in quotes, you use an @ and write the name of the file:

curl -X POST -d @data_file.txt https://www.whatever.com/api/post

POST with data from a JSON file:

Really, this is the limit of where I’d be using curl. Once we start getting into JSON formatting, we have to start worrying about making header changes for the encoding, being exact in our formatting, being unsure of our server’s requirements, and so we hit a point of diminishing returns on what was supposed to be “simple”. For the sake of being thorough, I’ll include this example, but you as can see, it isn’t something I’d write off the top of my head…

curl -X POST -d @datafile.json -H "Content-Type: application/application-json" https://localhost:1337/api/post

Cheers!

Outside Resouces

• curl’s official site: curl.se - See https://curl.se/docs/manual.html and https://curl.se/docs/faq.html
• For a summary version of some other points I found a gist by a ‘btoone’ that summarizes a lot about curl
• Even briefer, I found a gist by a ‘subfuzion’ about curl
• For FULL details, as always, man curl for the built in manual.

❯ ★ ✎ ✦ ✮ ✯ ❂ ⦿ ❯ ★ ✎ ✦ ✮ ✯ ❂ ⦿ ❯ ★ ✎ ✦ ✮ ✯ ❂ ⦿ ❯ ★ ✎ ✦