curl for REST API requests

Nov 20, 2019
misc utils shell command-line

This post discusses how to use curl for making REST API requests from the command line. curl is an open-source tool for transferring data that supports protocols like HTTP, FTP among others. For demonstrating the usage of curl, we will be hitting a public REST API hosted at typicode - We are going to play around with the posts resource in the above API. Since we aren’t setup anything locally, just copy-pasting the below-mentioned snippets to your shell should work automatically. Let’s dive right in, without further ado.

GET request

GET requests are the simplest to make. We just need to pass the API URL as the argument to the curl command.

curl https://jsonplaceholder.typicode.com/posts

Any path param can be appended to the URL - The following request fetches posts with id as 1

curl https://jsonplaceholder.typicode.com/posts/1

We can also use query params with the request, by adding them to the URL - The following fetches the posts with userId as 1

curl https://jsonplaceholder.typicode.com/posts?userId=1

We can use mutiple query params separated by an &(ampersand), but the URL string needs to be enclosed within double quotes in this case. The reason is that & is also used to start background jobs from the shell - Without the quotes, the shell would think that it is the end of the command (thereby stop reading the other query params ), and run the curl command in the background.

curl  "https://jsonplaceholder.typicode.com/posts?userId=1&id=6"

One thing to note is that, for the POST/PUT/DELETE requests here, the resource will not actually be modified on the server, but will be faked as if it is. Also, (for clarity) the commands are split into multiple lines - if you are copy-pasting from here, please merge into one line(remove line breaks) before trying out the command on the shell/terminal.

POST request

The following is a sample POST request using cURL. The meanings for the different arguments are explained below.

curl -H 'Content-Type: application/json' 
-d '{"userId":1,"id":1,"title":"sample title","body":"sample body"}' 
-X POST https://jsonplaceholder.typicode.com/posts

-H - Used to denote the request headers (cURL uses application/x-www-form-urlencoded as the default Content-Type, when used with the -d parameter. For JSON APIs, we need to the explicitly pass application/json as the Content -Type).

-d - Denotes the request data (API payload). Since the request payload contains double-quotes, the payload need to be enclosed in single-quotes.

-X - Request type (POST, PUT, DELETE, etc)

In case you need to pass multiple headers, use the -H parameter multiple times. For example,

curl -H 'Content-Type: application/json' -H 'My-Header-Name: My-Header-Value' 
-d '{"userId":1,"id":1,"title":"sample title","body":"sample body"}' 
-X POST https://jsonplaceholder.typicode.com/posts

You can also store the request payload in a file and use it with curl, as shown in the next section.

PUT request

curl -H 'Content-Type: application/json'
-d '{"userId":1,"id":1,"title":"sample title","body":"sample body"}' 
-X PUT https://jsonplaceholder.typicode.com/posts/1

The PUT request is very similar to the POST example above, with a couple of minor tweaks:

Pass PUT as the request method (for the -X option)
PUT is used to update an existing resource, so the id of the resource needs to be passed in the URL

PATCH Request

The PATCH request is very similar to PUT, except that we need to specify PATCH as the request method for the -X option.

curl -H 'Content-Type: application/json' 
-d '{"userId":1,"id":1,"title":"sample title","body":"sample body"}' 
-X PATCH https://jsonplaceholder.typicode.com/posts/1

HTTP DELETE request

For DELETE APIs, we need to use DELETE as the argument to -X. Delete APIs don’t require a payload or header normally, so can skip the -d and -H options as below:

curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

Gotchas!

Now that we have covered how to make API requests using cURL for different HTTP methods, it’s time to enhance our expertise with some neat little capabilities cURL provides.

Read from file

We can pass a file containing the request payload to the -d option, as below (Create a file named request.json in the current directory and add the request payload, before trying out the command):

curl -d @request.json -H "Content-Type: application/json" https://jsonplaceholder.typicode.com/posts

This option is extremely useful especially when dealing with large request payloads.

Write to file

It is also possible to write the response body to a file using the -o option - The command below creates a file named response.json and writes the response payload to it.

curl -o response.json https://jsonplaceholder.typicode.com/posts/1

If we would like to read request from file, and write response to file:

curl -o response.json -d @request.json -H "Content-Type: application/json" https://jsonplaceholder.typicode.com/posts

Verbose Output

curl -v https://jsonplaceholder.typicode.com/posts/1

For the API requests we have been trying out so far, cURL outputs only the response payload to the console - It doesn ’t provide any information on the status code of response, response headers, etc. The -v option solves this use case - It prints out the HTTP status code, useful request + response headers (Content-Type, Content-Length, cookies, etc ) which comes in handy while troubleshooting issues.

Format Json

And last but not the least, we can pretty-print the response json, as below (Should work as long as you have Python installed on your machine):

curl  https://jsonplaceholder.typicode.com/posts/1 | python -m json.tool

The jq tool, supports a multitude of other options(extracting certain elements from payload, etc) in addition to pretty-printing, but you have to take the pain of installing it.

curl  https://jsonplaceholder.typicode.com/posts/1 | jq '.'

Conclusion

We can also use tools like Postman or Insomnia to invoke REST APIs. They provide advanced features like collections, collection-runner, history, etc.However, if you are a command -liner and wanna try an API quickly without taking your hands off the keyboard, the curl utility is your best friend. I hope you found the post useful 😄 Thanks for reading.