How to Send JSON Data with curl: A Complete Guide

When working with REST APIs, you’ll often need to send JSON data in your requests. curl is a powerful command-line tool that makes this process straightforward. In this guide, we’ll explore how to send JSON payloads using curl, both directly from the command line and from files.

Sending JSON from the Command Line

The most basic way to send JSON data is to include it directly in your curl command. You’ll need two essential flags:

• -X POST: Specifies the HTTP method (POST in this case)
• -H "Content-Type: application/json": Sets the content type header
• -d: Specifies the data to send

Here’s a simple example:

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"name": "John Doe", "email": "john@example.com"}' \
     http://api.example.com/users

For better readability with complex JSON, you can use multiple lines:

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "name": "John Doe",
       "email": "john@example.com",
       "address": {
         "street": "123 Main St",
         "city": "Anytown",
         "country": "USA"
       }
     }' \
     http://api.example.com/users

Sending JSON from a File

When working with larger JSON payloads or when you want to reuse the same data multiple times, storing the JSON in a file is more convenient. Here’s how to do it:

1. First, create a JSON file (e.g., payload.json):

{
  "name": "John Doe",
  "email": "john@example.com",
  "preferences": {
    "theme": "dark",
    "notifications": true,
    "language": "en"
  }
}

2. Then use the @ symbol to reference the file in your curl command:

curl -X POST \
     -H "Content-Type: application/json" \
     -d @payload.json \
     http://api.example.com/users

Additional Tips

Viewing the Response

Add the -i flag to see the response headers:

curl -X POST \
     -H "Content-Type: application/json" \
     -d @payload.json \
     -i \
     http://api.example.com/users

Pretty-Printing the Response

If the API returns JSON, you can pipe the output to jq for pretty-printing:

curl -X POST \
     -H "Content-Type: application/json" \
     -d @payload.json \
     http://api.example.com/users | jq '.'

Handling Authentication

Many APIs require authentication. You can include an authorization header like this:

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-token-here" \
     -d @payload.json \
     http://api.example.com/users

Common Issues and Solutions

1. Escaping Special Characters: When sending JSON directly in the command line, remember to escape special characters properly. Using a file avoids this issue.

2. Windows Command Prompt: If you’re using Windows Command Prompt, you’ll need to use double quotes instead of single quotes:

curl -X POST ^
     -H "Content-Type: application/json" ^
     -d "{\"name\": \"John Doe\"}" ^
     http://api.example.com/users

3. Invalid JSON: Always validate your JSON before sending it. You can use online tools or jq:

jq '.' payload.json

Conclusion

curl is a versatile tool for working with JSON APIs. Whether you’re sending simple or complex JSON payloads, using the command line or files, these examples should help you make API requests effectively.

Remember to replace http://api.example.com/users with your actual API endpoint in all examples. Always check your API’s documentation for specific requirements regarding headers, authentication, and data format.