Getting Started with cURL: A Beginner's Guide

Let's Talk About Servers First

Before we jump into cURL, here's something you need to know: a server is just a computer sitting somewhere that has information you want. When you open Instagram on your phone, your app asks Instagram's server "hey, show me my feed" and the server sends back all those photos and videos.

Pretty simple, right? Your device asks, the server answers.

Now here's the thing - your browser is great for visiting websites, but what if you're building something? What if you need to test if your backend code actually works? You can't just keep refreshing your browser hoping things work.

That's where cURL comes in.

So What Exactly is cURL?

cURL is just a way to talk to servers using your terminal instead of a browser. That's it.

Think about ordering food:

• Browser = Calling the restaurant and having a whole conversation

• cURL = Texting them "1 large pizza, extra cheese, my address"

Both work, but one's way faster when you know exactly what you want.

The name "cURL" stands for "Client URL" but honestly, you don't need to remember that. Just know it's a tool that sends requests to servers.

Why Should You Care About cURL?

Here's why every developer I know uses cURL:

1. Test your APIs instantly
You just wrote some backend code. Does it work? Instead of building a whole frontend to test it, just fire off a cURL command. Boom, you know in 2 seconds.

2. Debug stuff when things break
User says "the app isn't working!" You can use cURL to see exactly what the server is sending back. No guessing games.

3. Automate boring tasks
Need to download 50 files? Or check if a website is up every 5 minutes? Write a script with cURL and let it run.

4. Learn how the web actually works
Browsers hide a lot of stuff from you. cURL shows you the raw conversation between your computer and the server. It's like seeing the Matrix.

5. Work anywhere
SSH'd into a remote server? No browser there. But cURL? Always available.

Your First cURL Request

Alright, enough theory. Let's actually do something.

Open your terminal and type this:

curl https://example.com

Hit enter. You'll see a bunch of HTML code fly by. Congrats! You just asked example.com's server for its homepage, and it sent you the raw HTML.

Not super exciting, I know. Let's try something cooler:

curl https://api.github.com

Now you're getting data from GitHub's API. It's in JSON format (looks like a bunch of curly braces and quotes). This is the same kind of data your apps use behind the scenes.

Want to make it look nicer? Try this:

curl https://api.github.com | jq

(You might need to install jq first, but it makes JSON actually readable)

Understanding What Just Happened

Every time you use cURL, two things happen:

1. You send a request to the server

2. The server sends back a response

Let's break down what that looks like:

What's in a Request?

When you run curl https://api.example.com/users, you're actually sending something like this:

GET /users HTTP/1.1
Host: api.example.com
User-Agent: curl/7.68.0
Accept: */*

Translation:

• "Hey server, I want to GET the /users data"

• "I'm using cURL to make this request"

• "I'll accept whatever format you send back"

What's in a Response?

The server sends back:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1234

{
  "users": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ]
}

Translation:

• "Everything's good (200 OK)"

• "I'm sending you JSON data"

• "Here's the actual data you asked for"

Visual Breakdown

Here's what the complete HTTP request and response structure looks like:

Status Codes You'll See All The Time

Actually Using cURL with APIs

APIs are how apps talk to each other. Let's learn the two most important types of requests: GET and POST.

GET - When You Want Data

GET is for grabbing information. Like asking "what's in the fridge?"

Get a list of users:

curl https://jsonplaceholder.typicode.com/users

This hits a fake API (great for practice) and gets you a list of users.

Get one specific user:

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

Just user #1 this time.

Search for something:

curl "https://api.example.com/search?q=javascript&limit=10"

The ?q=javascript&limit=10 part is like adding filters. "Search for javascript, show me 10 results."

POST - When You're Sending Data

POST is for creating or updating stuff. Like putting groceries IN the fridge.

Create a new post:

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Post",
    "body": "This is the content",
    "userId": 1
  }'

Let me break this down:

• -X POST means "use the POST method"

• -H "Content-Type: application/json" tells the server "I'm sending JSON"

• -d '{...}' is the actual data you're sending

Send form data (like a login):

curl -X POST https://example.com/login \
  -d "username=alice" \
  -d "password=secret123"

This is like filling out a form and hitting submit.

How This Fits Into Real Development

Here's the workflow:

1. You write backend code

2. Test it immediately with cURL (no frontend needed yet!)

3. If it works, great! Build the frontend

4. If not, fix it and test again

Way faster than building a whole UI just to test one endpoint.

Mistakes I Made (So You Don't Have To)

Mistake #1: Forgetting Quotes

This breaks:

curl https://api.example.com/search?q=hello world

This works:

curl "https://api.example.com/search?q=hello world"

Why? That space in "hello world" confuses your terminal. Quotes keep everything together.

Mistake #2: Not Telling the Server What You're Sending

This might not work:

curl -X POST https://api.example.com/users \
  -d '{"name": "Alice"}'

This will work:

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

The server needs to know you're sending JSON, not just random text.

Mistake #3: Not Checking If It Actually Worked

Bad habit:

curl https://api.example.com/users/999
# Sees nothing, assumes it worked

Better:

curl -i https://api.example.com/users/999
# Sees "404 Not Found" - oh, that user doesn't exist!

The -i flag shows you the status code. Always check it!

Mistake #4: Using GET When You Should Use POST

Wrong:

curl "https://api.example.com/create-user?name=Alice"

Right:

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

GET is for reading data. POST is for creating or changing data. Don't mix them up.

Mistake #5: Going Overboard with Flags

When you're starting out, keep it simple:

Don't do this yet:

curl -X GET -H "Accept: application/json" -H "User-Agent: MyApp/1.0" \
  -H "Accept-Encoding: gzip, deflate" -v --trace-ascii - \
  https://api.example.com/users

Start here:

curl https://api.example.com/users

Add complexity only when you need it. Don't copy-paste commands you don't understand.

Mistake #6: Losing Your Response

Annoying:

curl https://api.example.com/huge-data
# Scrolls past super fast, can't read it

Smart:

curl https://api.example.com/huge-data > data.json
# Saved to a file, read it whenever

Big responses? Save them to a file.

Mistake #7: Forgetting Authentication

This fails:

curl https://api.example.com/my-private-data
# Returns 401 Unauthorized

This works:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/my-private-data

Most real APIs need some kind of authentication. Check their docs for how to do it.

Quick Cheat Sheet

Here are the commands I use most often:

Basic stuff:

# Simple request
curl https://api.example.com/users

# See the full response with headers
curl -i https://api.example.com/users

# See EVERYTHING (debugging mode)
curl -v https://api.example.com/users

# Save to a file
curl https://api.example.com/users -o users.json

Sending data:

# POST with JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# POST like a form
curl -X POST https://api.example.com/login \
  -d "username=alice" \
  -d "password=secret"

Authentication:

# Bearer token (most common)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/protected

# Basic auth (username + password)
curl -u username:password https://api.example.com/protected

Custom headers:

# One header
curl -H "Accept: application/json" https://api.example.com/users

# Multiple headers
curl -H "Accept: application/json" \
  -H "User-Agent: MyApp/1.0" \
  https://api.example.com/users

Wrapping Up

Look, cURL isn't complicated. It's just a way to talk to servers from your terminal. Once you get comfortable with it, you'll wonder how you ever lived without it.

Start simple:

1. Try the basic GET examples above

2. Play with JSONPlaceholder - it's a fake API made for practice

3. Test the GitHub API - no auth needed for basic stuff

4. When you're ready, try POST requests

Don't try to memorize all the flags and options. I've been coding for years and I still Google "how to send a file with cURL" every time I need it.

The point is to build confidence. Start with curl https://example.com and go from there.

You got this! 🚀

---