You might have used tools like Postman and Insomnia to test API endpoints of your application. These interactive tools offer the Graphical User Interface(GUI) with additional features. Meanwhile, you can perform the same task with a minimalist approach. That is where tools like cURL come into action. It can be used whether as a CLI utility or as a script in a programming language.
To make a POST request using cURL, use curl command along with the -X flag followed by the word POST and the url you are making the request to. Below is an example of making a POST request:
curl -X POST http://www.google.com/cURL supports tons of network protocols like HTTP, HTTPS, IMAP, POP3, SMTP, etc. This article will mainly emphasize using cURL with the HTTP protocol and will be a comprehensive guide to making a POST request using cURL.
Table of Contents
Introduction to cURL
cURL stands for Client URL and is available by using the libcurl library. It is primarily used as a command-line tool for sending and receiving data over a network protocol. In most of the major Linux distributions, cURL is preinstalled. You can verify its installation by using the following command in the terminal.
curl -VThe command above will show the cURL version installed in your system. If cURL is not installed in your system, type the following command in the terminal to install it.
sudo apt-get install curlNote: The above command works for Ubuntu and Debian-based system.
The basic syntax of the cURL command looks like this:
curl [options] <url>Here, [options] are represented by flags such as -d,-f, -h, etc., while <url> is the host where the request is to be sent.
Let’s see a basic example of sending a POST request.
curl -X POST http://www.example.com/The -X flag denotes the HTTP request sent to the host. Here, the POST request is sent to the host https://www.example.com/. The example is only meant for the purpose of understanding the working of curl with POST requests. It is not operational.
In the sections below, you will learn how to send data to the host using the POST method.
Creating POST Request using cURL
While using cURL to send a POST request, you can send data in a number of formats. You need to use relevant options in the command to specify the data formats and data. The following portion of the article will guide you on that. Keep reading on!
Sending the Data with the POST Request using cURL
The -d or the -data flag is used as an option of the curl command to send the data with the POST request to an HTTP host. A common example of a POST request is an application sending the form data to the server. While emulating it using the curl command, the -d option makes it possible. The quotes followed by the -d flag accommodate the data to be sent. You can emulate a similar POST request using the curl command as follows:
curl -X POST https://jsonplaceholder.typicode.com/todos -d "UserId=1" -d "id=201" -d "title=go shopping" -d "completed=true"Here, the URL https://jsonplaceholder.typicode.com/todos is the API endpoint where you just sent the POST request. It is a dummy API that can be used for testing. The data inside the double quotes after the -d flag is sent to the server.
Note: We have used a dummy API endpoint, https://jsonplaceholder.typicode.com/todos, in the examples in this article. The examples do not really create new resources on the server. However, it is used to show how to use the -d flag.
In the example above, notice the use of the multiple -d options to send each pair of data. There’s a better and shorter way to write it. You can use the ampersand symbol(&) to concatenate each pair of data and send it with a single -d option. Below is an example of using &.
curl -X POST https://jsonplaceholder.typicode.com/todos -d "UserId=1&id=201&title=go shopping&completed=true"
After sending the request, the server sends the response as follows:
{
"UserId": "1",
"id": 201,
"title": "go shopping",
"completed": "true"
}Setting the Content-Type in a POST Request using cURL
The curl command lets you choose different data formats while sending a POST request. You can use the -H option along with the curl command to specify the Content-Type representational header to send a request with the specific data format.
The most common and widely used data formats while sending a POST request are JSON, form-data and URL encoded. Thus, you can set the Content-Types like application/json, multipart/form-data and application/x-www-form-urlencoded for the respective data formats to make a request.
Let’s consider an example of sending a POST request with JSON data as a payload.
curl -X POST https://jsonplaceholder.typicode.com/todos -H "Content-Type: application/json" -d '{"UserId":1,"id":201,"title":"go to gym","completed":true }'The example shows that JSON data is supplied with the -d flag. In order to notify the server that the JSON data is being sent, you need to specify the Content-Type as application/json in the header with the -H flag as above.
After making the request, the server acknowledges the data as JSON and sends back a response as follows:
{
"UserId": 1,
"id": 201,
"title": "go to gym",
"completed": true
}If you do not specify the Content-Type of a request, the default is application/x-www-form-urlencoded. It is primarily used to send ASCII values during a request. The first two examples in the article represent this behavior.
Sending a File with the POST Request using cURL
You can also send a file with POST request using the curl command. The -F option, along with the curl command or the Content-Type set to multipart/form-data with the -H option, makes it possible to send the file. You can either use one of these two methods to achieve the goal. When you use the -F option, it automatically sets the Content-Type to multipart/form-data.
The Content-Type multipart/form-data enables the server to receive non-ASCII and large-sized input. The typical scenario of using the content type is while uploading a file.
curl -X POST http://example.com/posts -F "image=@/home/images/sample.png"Note: While setting the file location, do not forget to add the @ symbol at the start of the file path.
You just uploaded an image file with the POST request hitting the endpoint http://example.com/posts.
Conclusion
cURL ranks in one of the best positions with the efficacy to provide a forthright approach to communicating with the server. Right after its installation, you can access it from the terminal, and you are ready to go. The article introduced cURL, guided you through the installation process and demonstrated how to use it with the HTTP POST request. Hopefully you learned how to use the different options like -d, -Hand -F and send the POST request with the curl command.
Did the article acquaint you with the concept of cURL?
Share your comments with us on our Twitter account of Become A Better Programmer.