Getting Started with cURL

You've probably seen the word curl in many tutorials or documentation. We know it's used to "talk" to websites or APIs by typing commands.

As developers, we're familiar with that, but have you ever wondered how cURL does this? why It's ideal for testing internet connections etc?

Before understanding cURL, let's first understand what a "Server" is and why we need to communicate with it.

Example: Imagine you're at a restaurant and you want something. You can't just walk into the kitchen and help yourself, so you have to talk to the Waiter.

The Waiter takes your request to the kitchen (the Server) and then brings back your food (the Response).

In the tech world, every website and photo lives on a server. To access them, your computer has to request them.

so, that where cURL comes in the picture, Usually, we use a web browser (like Chrome or Safari) to talk to servers. Browsers are great because they make everything look pretty with colors and buttons.

But, cURL is simply a way to talk to those same servers directly from your Terminal.

What is cURL?

cURL (pronounced “curl”) is a command-line tool and library used for transferring data to or from a server using various protocols, most commonly HTTP, HTTPS, FTP, and more. It’s widely used for testing APIs, downloading files, or sending requests over the internet.

Why programmers need cURL?

You might have doubt, if we have browsers where we can test so, why need cURL?

ahh, Browsers are good for non programmers, but they are "heavy” & They load images, ads, and fancy fonts etc which make slow.

Where we Programmers use cURL because, it’s fast why?

cURL give you the raw data instantly meaning It shows you exactly what the server is giving payload (data) without any "makeup" or pretty design like browser does and we programmers need to know real payloads to work with it.

Speed: It’s way faster to type a command than to click through five pages.
Automation: You can write a script that uses cURL to check the weather or update a database every hour.
Debugging: When a website is broken, cURL shows you the raw "truth" of what the server is saying without the browser trying to "fix" or hide the errors.

Making your first request using cURL?

Let’s us do, our frist request using cURL, go to command and type curl https://www.google.com.

You will see a huge unstructure code, so what we did? we just ask google server to give google.com homepage and handed to you.

cURL        Server        Database
  |            |             |
  | Request -->|             |
  |            | Query --->  |
  |            |             |
  |            | <--- Data   |
  | <-------- Response       |

Understanding request and response?

To understand what a request and response are while running the command curl https://www.google.com, they secretly handshake:

The request is: send me google.com (if we talk about HTTP protocol properties, it uses the GET property)

The response is: what the server sends back. (if we talk about HTTP protocol properties, it uses the POST property) and Response usually send with payload, status code, error message etc.

And the some of status code are:

200: "All good! Here’s your data."
404: "I can’t find what you’re looking for."
500: "Oops, my server is having a bad day."

Additionally, here is MDN docs to read all different types of status code.

Meaning:

GET → retrieve data (sent in URL)
POST → send data (sent in request body)

Using cURL to talk to APIs?

As programmers, we often use cURL, and this is where the magic happens. APIs let apps talk to each other. If you want to get some "placeholder" data from a public API, try this:

curl https://jsonplaceholder.typicode.com/posts/1

Instead of messy HTML, you'll get a clean piece of data called JSON. It looks like a list of properties (UserId, Title, Body). Programmers use cURL to test these connections to ensure their apps can "read" the data correctly.

Basic GET Request : curl https://api.example.com/data (This prints the response (usually JSON) to your terminal)
GET Request with Query Parameters: curl "https://api.example.com/data?user_id=123&limit=10" (Wrap the URL in quotes if it contains & or other special characters)

GET Request with Headers: APIs often require authentication or other headers.

 curl -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Accept: application/json" \
      https://api.example.com/data

 1. -H → Adds an HTTP header
 2. Authorization → Common for API keys or tokens
 3. Accept → Tells the server what format you want (JSON, XML, etc.)

POST Request with JSON Data: To send data (like creating a new record), use POST with -d for the data and set the content type.

 curl -X POST https://api.example.com/data \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{"name": "Alice", "email": "alice@example.com"}'

 1. -X POST → Specifies the HTTP method
 2. -d → The JSON payload to send
 3. Content-Type: application/json → Required when sending JSON

PUT or PATCH Request: Used to update data:

 curl -X PUT https://api.example.com/data/123 \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{"email": "alice_new@example.com"}'

 1. PUT → Replaces the resource entirely.
 2. PATCH → Updates only the fields provided.

DELETE Request: To remove a resource:

 curl -X DELETE https://api.example.com/data/123 \
      -H "Authorization: Bearer YOUR_API_KEY"

Common Mistakes Beginners Make with cURL

As beginner developers, we might have a lot of confusion and make some mistakes. Here is one mistake often made:

Forgetting the Quotes: If your URL has special characters (like & or ?), always wrap it in quotes: curl "https://api.com/search?q=hi".

Ignoring the Headers: Sometimes a server rejects your request because it doesn't know who you are. You might need to add -H to send an "ID card" (API Key).
Not Using -v (Verbose): If something isn't working, beginners often stare at a blank screen. Add -v to your command (e.g., curl -v google.com) to see the entire conversation. It’s like turning on the lights in a dark room.