cURL POST JSON

cURL is a powerful command-line tool used for transferring data between servers, including HTTP requests and responses. It supports various protocols, including HTTP, HTTPS, FTP, and many others. In this blog post, we will focus on using cURL to make a JSON POST request. JSON (JavaScript Object Notation) is a lightweight data format that is easy to read and write. It is commonly used for sending and receiving data between web applications. We will show you how to send a JSON payload with a POST request using cURL.



Prerequisites:

Before we dive into the technical details, let’s make sure that you have the necessary tools installed on your system. You will need:

  • cURL (version 7.18.0 or higher)
  • A text editor of your choice (e.g. Notepad++, Sublime Text, Visual Studio Code)


Step 1: Define the JSON Payload

Before making a JSON POST request with cURL, you need to define the JSON payload that will be sent with the request. A JSON payload is simply a string of text that represents a JavaScript object, and it is usually passed as a string in the cURL command.

Here’s an example JSON payload that we will use throughout this post:

{
    "name": "John Doe",
    "email": "johndoe@example.com",
    "phone": "555-555-5555"
}

This payload contains three key-value pairs, representing a person’s name, email, and phone number.



Step 2: Test the API Endpoint

Before sending the JSON POST request, it’s a good idea to test the API endpoint with a GET request to make sure it’s working as expected. You can use cURL to make a GET request by simply specifying the URL:

curl https://example.com/api/user/1

This will send a GET request to the URL “https://example.com/api/user/1” and display the response in the console.



Step 3: Make the JSON POST Request

Now that we have the JSON payload and have tested the API endpoint, we can use cURL to make the JSON POST request. Here’s the basic cURL command to make a JSON POST request:

curl -X POST -H "Content-Type: application/json" -d '{"name": "John Doe", "email": "johndoe@example.com", "phone": "555-555-5555"}' https://example.com/api/user/create

Let’s break down this command:

  • “-X POST”: specifies that we want to make a POST request
  • “-H “Content-Type: application/json””: sets the “Content-Type” header to “application/json”, indicating that the payload is in JSON format
  • “-d ‘{“name”: “John Doe”, “email”: “johndoe@example.com“, “phone”: “555-555-5555″}’”: specifies the JSON payload to send with the request
  • “https://example.com/api/user/create“: specifies the URL to send the request to

When you run this command, cURL will send a JSON POST request to the specified URL with the payload we defined earlier.



Step 4: Handle Errors

If there is an error with the JSON POST request, cURL will display an error message in the console. Common errors include invalid JSON syntax, missing required fields, and server-side errors. If you encounter an error, you can refer to the API documentation and cURL documentation to troubleshoot the issue. Additionally, you can use the “-v” option in cURL to display even more detailed information about the request and response.

In some cases, the API endpoint may return an error response. To handle errors, you can use the “-w” option in cURL to display additional information about the request and response. For example, you can run the following command:

curl -X POST -H "Content-Type: application/json" -d @payload.json -w "\nHTTP status: %{http_code}\nTotal time: %{time_total}\n" https://example.com/api/user/create

This command adds the “-w” option with a format string that displays the HTTP status code and the total time taken to complete the request. If the API endpoint returns an error response, you can use this information to troubleshoot the issue. Additionally, you can use the “-v” option in cURL to display even more detailed information about the request and response.



Step 5: Use Variables in the JSON Payload

In some cases, you may want to use variables in the JSON payload to send dynamic data with the request. You can do this by using string interpolation in the payload file. For example, let’s say you have a variable named “username” that you want to send with the request. You can modify the payload.json file as follows:

{
    "name": "John Doe",
    "email": "johndoe@example.com",
    "username": "${username}"
}

When you run the cURL command, you can pass the value of the “username” variable using the “-d” option. For example:

curl -X POST -H "Content-Type: application/json" -d '{"username": "johndoe"}' https://example.com/api/user/create

This will send a POST request with the JSON payload:

{
    "name": "John Doe",
    "email": "johndoe@example.com",
    "username": "johndoe"
}


Step 6: Use cURL with Bash Scripts

If you need to make multiple requests with cURL or automate the process, you can use cURL with Bash scripts. Bash is a popular shell scripting language that is available on most Unix-based systems, including Linux and macOS.

Here’s an example Bash script that uses cURL to make a JSON POST request:

#!/bin/bash

# Define variables
url="https://example.com/api/user/create"
payload='{"name": "John Doe", "email": "johndoe@example.com"}'

# Make the request
response=$(curl -X POST -H "Content-Type: application/json" -d "$payload" "$url")

# Print the response
echo "$response"

This script defines the URL and JSON payload as variables and uses the cURL command to make the POST request. The response from the server is stored in the “response” variable, which is then printed to the console.



Conclusion:

In this blog post, we have shown you how to use cURL to make a JSON POST request. We started by defining the JSON payload and testing the API endpoint, and then we used cURL to send the POST request. We also discussed how to handle errors, use variables in the payload, and use cURL with Bash scripts. We hope that this guide has been helpful and that you can now use cURL to make JSON POST requests with confidence.



Leave a Reply