Perform a POST Request Using Curl [Practical Examples]

What is Curl?

cURL, which stands for Client URL, is an open-source command-line utility mainly used by developers to transfer data to or from a server via the different supported protocols. The supported protocols include HTTP POST, HTTP PUT, FTP file upload, web form submission, user authentication, HTTP Cookies, HTTP, HTTPS, FTP, FTPS, SFTP, built-in SSL certificates and much more. This utility comes installed by default on most Linux distributions and macOS and is also available for Windows.

This utility is mainly utilized by developers who test APIs, view server responses and make HTTP requests. In this article, we will give you a detailed guide on how to perform a POST request using cURL.

What is HTTP POST Request Method?

HyperText Transfer Protocol (HTTP) is a request-response protocol that enables communications between Client machines and Servers. For example, when you search for something on the browser, your PC sends a POST request to the server, which sends back a response. The response contains status information about the sent request and the requested content.

There are several HTTP methods. These include POST, GET, PUT, HEAD, DELETE, PATCH, and OPTIONS. However, the most common are POST and GET. Data sent from the browser to the server using the HTTP POST method is stored in the request body, as shown below.

POST /test/demo_form.php HTTP/1.1
Content-Type: application/json
Content-Length: 1024
Host: golinuxcloud.com

Sending a POST Request with Curl

You can see all the parameters required to send POST requests from the code above. We first need to specify the HTTP method using the -X parameter. In this case, it's the POST method. Next, we need to specify the Content-type using the -H parameter. That enables the server to identify the data type of the request body and process it accordingly. There are two Content-Type options.  application/x-www-form-urlencoded which is used when submitting a web form to the server and  multipart/form-data which is used to upload files to the server.

You use the -F parameter to send the data using multipart/form-data Content-Type and -d to send data using the application/x-www-form-urlencoded Content-Type. The final parameter is the host/ server. Here you can type the URL of your target website. See the default CURL syntax for sending a POST request below.

curl -X POST [options] [URL]

Make a Simple POST Request with CURL

To make a basic POST request with the Curl command, execute the command below on your Terminal.

curl -X POST https://example.com

Send Additional Fields in a Curl Post Request

We can use the -d parameter to send additional data in a POST request. Remember, using this parameter also specifies the Content-Type/ default header as application/x-www-form-urlencoded. To better understand how we can send additional fields, let's look at the simple HTML code below.

This code renders a simple login screen on the browser with three main fields. The username field, which uses the input name "user," the password field, which uses the input name "pass," and the login button. You can also see the HTTP method used to submit this data to the server is POST.

After typing your username, password and clicking the Login button, this data is submitted to the Node-JS code below.

We will put our focus on two lines in the code above.

var username = req.body.user;
var password = req.body.pass;

The first line var username = req.body.user; reads the user input in the username field and stores it in the username variable. Remember, that's the field that uses the input name "user," as shown in the HTML code. The second line var password = req.body.pass; reads the user input in the password field and stores it in the password variable. Remember, that's the field that uses the input name "pass," as shown in the HTML code. After processing the user inputs, the NodeJS code will either render the "LOGIN SUCCESS" message or "INVALID CREDENTIALS" on the browser.

Since we know the input names used for the different fields, instead of launching the browser and typing the username and password directly, we can use CURL to send this information and render the server response on the Terminal. Isn't that exciting? It even sounds more like browser automation. Let's look at the command syntax we will use to achieve that.

curl -d "[Input-Name]=[Your-UserName] & [Input-Pass]=[Your-UserPassword]" -X POST [Target-Host]

Let's use the syntax above to write our command:

curl -d "user=johndoe & pass=12345" -X POST http://localhost:3000/

NB: I have included some echo parameters in the command to get a clean Terminal output.

Using the image above, I typed the correct credentials in the first command, and we got a "LOGIN SUCCESS" message. I used the wrong username in the second command, and we got the "INVALID CREDENTIALS" message.

Specify the Content-Type in POST Request with Curl

If you wish to use a specific header or Content-Type, you can use the -H parameter. For example, we can modify the command above by including the application/x-www-form-urlencoded header, as shown below.

echo; curl -d "user=johndoe&pass=12345" -H "Content-Type: application/x-www-form-urlencoded" -X POST http://192.168.1.52:3001/; echo; echo

And here is the interesting bit. Let's try to specify the Content-Type to something else like application/json.

echo; curl -d "user=johndoe&pass=12345" -H "Content-Type: application/json" -X POST http://192.168.1.52:3001/; echo; echo

Using the image above, even though I typed the correct credentials, we are getting the "INVALID CREDENTIALS" message. That brings us to the difference between application/x-www-form-urlencoded and application/json.

Upload Files with Curl Using the POST Method

To send a file with Curl via the POST method, we will use the -F parameter and add an @ symbol at the beginning of the file path. See the command below.

curl -X POST -F 'image=@/home/ubuntu-user/image.png' http://192.168.1.52:3001/upload

If you wanted to upload a document such as a pdf or a '.txt' file we will set the type as 'fileupload.' See the command below.

curl -X POST -F 'fileupload=@/home/ubuntu-user/textFile.txt' http://192.168.1.52:3001/upload

Conclusion

That's it! At this post, I believe you now have a good understanding of the CURL command and even know how to perform HTTP POST requests. For more information about Curl, you can check out the official documentation page. Do you have any queries or comments about this topic? If yes, please feel free to hit the comments below.