Logo
Back

How do I POST JSON data with cURL?

cURL is a versatile command-line tool that allows you to send and receive data using various network protocols. One of its most popular use cases is sending JSON data in a POST request to a server. Whether you’re building RESTful APIs, testing webhooks, or integrating with third-party services, understanding how to POST JSON data with cURL is an essential skill for modern developers.

What Is cURL?

cURL stands for Client URL and is used primarily to transfer data to or from a server using supported protocols like HTTP, HTTPS, FTP, and more. Thanks to its lightweight nature and broad compatibility, cURL has become a go-to utility in many development workflows.

Basic Steps to POST JSON Data with cURL

Below is the simplest form of a POST request that includes JSON data:

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"username": "JohnDoe", "email": "john@example.com"}' \
     https://api.example.com/users
  1. -X POST: Specifies that this is a POST request.
  2. -H "Content-Type: application/json": Sets the Content-Type header so the server knows the request body is JSON.
  3. -d '{"username": "JohnDoe", "email": "john@example.com"}': Supplies the raw JSON data.
  4. https://api.example.com/users: The endpoint URL where you want to send the data.

Adding Additional Headers

Often, you’ll need to pass authentication tokens or other custom headers with your request. Here’s how:

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your_access_token" \
     -d '{"username": "JohnDoe", "email": "john@example.com"}' \
     https://api.example.com/users
  • -H "Authorization: Bearer your_access_token" adds an authorization header required by many API services for secure access.

Using a File for JSON Data

If your JSON data is more complex or you want to maintain clean code, you can store the JSON in a file, then reference it:

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

In this example, @data.json indicates that the request payload comes from the local file named data.json.

Handling Response Data

After sending the request, cURL prints the server’s response to the console by default. You can use flags like -i to include headers or -v (verbose) for more detailed information about the request and response.

curl -X POST -H "Content-Type: application/json" \
     -d '{"username":"JohnDoe"}' -v \
     https://api.example.com/users

Common Errors and Tips

  • Malformed JSON: Always ensure your JSON is valid. Missing commas or incorrect quotes can lead to parse errors.
  • Incorrect Headers: If the server expects JSON, sending the wrong Content-Type can lead to 4xx errors (e.g., 400 Bad Request).
  • SSL Certificates: If you’re testing on a dev server without proper SSL certificates, you can bypass certificate validation using -k or --insecure, but never do this in production.

Strengthen Your Coding Skills

Working with cURL is a foundational skill, but robust coding and debugging abilities elevate your software engineering capabilities. If you’re looking to sharpen your understanding of coding patterns or JavaScript (which heavily influences JSON structures), here are two courses from DesignGurus.io that might help you level up:

  1. Grokking the Coding Interview: Patterns for Coding Questions
    Master the most common patterns behind coding interview questions and develop a systematic way to approach and solve problems.

  2. Grokking JavaScript Fundamentals
    A great resource for exploring the core concepts of JavaScript, including JSON manipulations and working with modern web APIs.

Final Thoughts

Using cURL to POST JSON data is straightforward once you grasp the basic syntax and understand how headers and data payloads work together. As you build APIs or integrate with external services, remember to validate your JSON, use the correct headers, and keep your environment secure. Mastering these fundamentals forms the backbone of efficient API development and testing.

Combine your cURL expertise with solid programming principles, and you’ll be well-equipped for building scalable, reliable systems—whether you’re coding scripts, designing microservices, or prepping for a technical interview.

CONTRIBUTOR
TechGrind