Getting Started with cURL: Your First Steps to Talking with Servers
What is a Server, and Why Do We Need to Talk to It?
Imagine you're at a restaurant. You (the client) want food, but you don't go into the kitchen yourself. Instead, you tell the waiter what you want, and the waiter brings it back to you. The kitchen is like a server – it has what you need, but you need to communicate with it properly.
In the web world:
You (your computer/browser) = The customer
The server = The kitchen that has the data/resources
The waiter = The communication method (HTTP)
When you visit a website, your browser automatically sends requests to servers and shows you the responses. But what if you want to send these requests yourself, without a browser? What if you're building an app and need to test if your server is working correctly?
This is where cURL comes in!
You (terminal) ──→ cURL ──→ Server (website/API)
↓
Response comes back to you
What is cURL? (In Very Simple Terms)
cURL stands for "Client URL" (though some say "See URL"). It's a command-line tool that lets you send requests to servers and see their responses – all from your terminal.
Think of cURL as your personal waiter that:
Takes your order (your request)
Goes to the kitchen (the server)
Brings back the food (the response)
Shows you exactly what happened
Real-world analogy:
Browser: "I'll handle ordering food for you automatically"
cURL: "Tell me exactly what to order, and I'll show you
everything that happens"
Why Do Programmers Need cURL?
1. Testing APIs Without Building a Full App
Instead of: Building a whole website to test if login works
Use cURL: Send a login request directly and see the response
2. Debugging Problems
Problem: "Why isn't my app getting data from the server?"
cURL helps: Send the exact same request to see what the server
actually returns
3. Automation
Scenario: Download a file every day at midnight
cURL: Write a script that uses cURL to fetch it automatically
4. Quick Checks
Question: "Is the server running?"
cURL: curl https://mywebsite.com
Response: If you get data back, it's running!
5. Documentation and Learning
Many API documentations show cURL examples because it's simple and works everywhere (Mac, Linux, Windows).
Making Your First Request Using cURL
Let's start with the absolute simplest command. Open your terminal and type:
curl https://example.com
What just happened?
You typed: curl https://example.com
↓
cURL sent request: "GET me the homepage of example.com"
↓
Server responded: Sent back HTML code
↓
Terminal shows: The HTML code of the webpage
You should see something like:
<!doctype html>
<html>
<head>
<title>Example Domain</title>
...
</head>
<body>
<h1>Example Domain</h1>
<p>This domain is for use in illustrative examples...</p>
</body>
</html>
🎉 Congratulations! You just made your first cURL request!
Understanding Request and Response
Every time you use cURL, two things happen:
The Request (What You Send)
┌─────────────────────────────────────┐
│ YOUR REQUEST │
├─────────────────────────────────────┤
│ Method: GET │
│ URL: https://example.com │
│ Headers: (browser info, etc.) │
│ Body: (empty for GET) │
└─────────────────────────────────────┘
│
↓
[Internet]
↓
The Response (What You Get Back)
┌─────────────────────────────────────┐
│ SERVER RESPONSE │
├─────────────────────────────────────┤
│ Status: 200 OK │
│ Headers: (content type, size, etc.) │
│ Body: The actual data (HTML, │
│ JSON, etc.) │
└─────────────────────────────────────┘
Seeing the Full Response
By default, cURL only shows you the body (the actual content). To see everything, use the -i flag:
curl -i https://example.com
Now you'll see:
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Content-Length: 1256
Date: Fri, 31 Jan 2026 10:30:00 GMT
<!doctype html>
<html>
...
Breaking it down:
HTTP/1.1 200 OK→ Status code (200 = success!)Content-Type: text/html→ The response is HTMLContent-Length: 1256→ The response is 1256 bytesEverything after the blank line → The actual content
Understanding Status Codes (The Server's Response Language)
When a server responds, it sends a status code to tell you what happened:
┌──────────┬─────────────────────────────────────────┐
│ Code │ Meaning │
├──────────┼─────────────────────────────────────────┤
│ 200 │ ✅ Success! Here's your data │
│ 201 │ ✅ Created! (data was saved) │
│ 400 │ ❌ Bad request (you sent wrong data) │
│ 401 │ ❌ Unauthorized (need to login) │
│ 404 │ ❌ Not found (page doesn't exist) │
│ 500 │ ❌ Server error (server broke) │
└──────────┴─────────────────────────────────────────┘
Example:
curl -i https://example.com/page-that-doesnt-exist
Response:
HTTP/1.1 404 Not Found
...
The 404 tells you the page wasn't found!
Using cURL to Talk to APIs
Most modern web applications use APIs (Application Programming Interfaces) to send and receive data. APIs often use JSON format instead of HTML.
Example: Getting Weather Data
Let's use a simple weather API (this is a made-up example for learning):
curl https://api.weather.com/current?city=London
Response might look like:
{
"city": "London",
"temperature": 15,
"condition": "Cloudy",
"humidity": 65
}
This is JSON – a way to structure data that's easy for programs to read!
HTML Response: For humans to read in browsers
JSON Response: For programs to read and process
Making Your JSON Response Readable
Raw JSON can be hard to read. Most systems have a tool to format it nicely:
Mac/Linux:
curl https://api.weather.com/current?city=London | jq
Or save it to a file:
curl https://api.weather.com/current?city=London > weather.json
The Two Most Important Request Types: GET and POST
There are different ways to ask a server for things. The two most common are GET and POST.
GET Request (Reading Data)
GET means: "Give me some data, but don't change anything"
Real-life analogy: "Show me the menu" (just reading, not ordering)
Examples:
# Get a webpage
curl https://example.com
# Get user information
curl https://api.example.com/users/123
# Search for something
curl "https://api.example.com/search?query=pizza"
Note: GET requests don't have a body – all information goes in the URL.
POST Request (Sending Data)
POST means: "Here's some data, please save/process it"
Real-life analogy: "I'd like to order this" (sending your order)
Example: Creating a new user
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"John","email":"john@example.com"}'
Breaking it down:
-X POST → Use POST method
-H "Content-Type: ..." → Tell server we're sending JSON
-d '{"name":"John"...}' → The data we're sending
Visual Comparison
┌─────────────────────────────────────────────────────────┐
│ GET vs POST │
├─────────────────────────────────────────────────────────┤
│ │
│ GET Request │
│ ┌───────────────────────────────────────┐ │
│ │ curl https://api.com/users/123 │ │
│ └───────────────────────────────────────┘ │
│ Purpose: Retrieve data │
│ Data location: In the URL │
│ Changes server?: No │
│ │
│ ───────────────────────────────────────── │
│ │
│ POST Request │
│ ┌───────────────────────────────────────┐ │
│ │ curl -X POST https://api.com/users \ │ │
│ │ -d '{"name":"John"}' │ │
│ └───────────────────────────────────────┘ │
│ Purpose: Send/create data │
│ Data location: In the request body │
│ Changes server?: Yes │
│ │
└─────────────────────────────────────────────────────────┘
Common Mistakes Beginners Make with cURL
1. Forgetting Quotes Around URLs with Special Characters
❌ Wrong:
curl https://api.example.com/search?query=hello world
The space in "hello world" breaks the command!
✅ Correct:
curl "https://api.example.com/search?query=hello world"
2. Not Checking the Status Code
❌ Mistake:
curl https://api.example.com/data
# Sees error HTML but thinks it worked
✅ Better:
curl -i https://api.example.com/data
# Now you see: HTTP/1.1 404 Not Found
3. Using Single Quotes for JSON on Windows
❌ Wrong (Windows):
curl -X POST https://api.com/users -d '{"name":"John"}'
Windows Command Prompt doesn't handle single quotes the same way!
✅ Correct (Windows):
curl -X POST https://api.com/users -d "{\"name\":\"John\"}"
Or better yet, use a file:
curl -X POST https://api.com/users -d @data.json
4. Not Specifying Content-Type for POST Requests
❌ Wrong:
curl -X POST https://api.com/users -d '{"name":"John"}'
Server might not understand you're sending JSON!
✅ Correct:
curl -X POST https://api.com/users \
-H "Content-Type: application/json" \
-d '{"name":"John"}'
5. Expecting Browser-Like Output for APIs
❌ Confusion:
curl https://api.example.com/data
# "Why am I seeing JSON instead of a nice webpage?"
✅ Understanding: APIs return raw data (usually JSON), not HTML webpages. This is intentional – the data is meant for programs, not humans browsing!
6. Not Following Redirects
Some URLs redirect to another location. By default, cURL doesn't follow them.
❌ Problem:
curl http://example.com
# Might just show a redirect message
✅ Solution:
curl -L http://example.com
# -L flag follows redirects
7. Forgetting Authentication
Many APIs require authentication (proving who you are).
❌ Wrong:
curl https://api.example.com/private-data
# Response: 401 Unauthorized
✅ Correct:
curl https://api.example.com/private-data \
-H "Authorization: Bearer YOUR_API_KEY"
Practical Examples to Build Confidence
Example 1: Check if a Website is Up
curl -I https://google.com
The -I flag means "just give me headers, not the full content"
Success looks like:
HTTP/1.1 200 OK
...
Example 2: Download a File
curl -O https://example.com/image.jpg
The -O flag saves the file with its original name.
Example 3: Save Response to a Custom File
curl https://api.example.com/data > mydata.json
Example 4: Send Form Data (Like Submitting a Form)
curl -X POST https://example.com/login \
-d "username=john" \
-d "password=secret123"
Example 5: See Full Request and Response Details (Debug Mode)
curl -v https://example.com
The -v (verbose) flag shows EVERYTHING that happens!
Quick Reference: Most Useful cURL Flags
┌────────────┬──────────────────────────────────────────┐
│ Flag │ What it does │
├────────────┼──────────────────────────────────────────┤
│ -X │ Specify request method (POST, PUT, etc.)│
│ -d │ Send data in request body │
│ -H │ Add a header │
│ -i │ Include response headers │
│ -I │ Headers only (no body) │
│ -o │ Save to file (custom name) │
│ -O │ Save to file (original name) │
│ -L │ Follow redirects │
│ -v │ Verbose (show everything) │
│ -s │ Silent (no progress bar) │
│ --help │ Show all available options │
└────────────┴──────────────────────────────────────────┘
Your First Real-World Task: Test a Public API
Let's practice with a real, free API – JSONPlaceholder (a fake API for testing):
Task 1: Get All Posts
curl https://jsonplaceholder.typicode.com/posts
You'll see a JSON array of fake blog posts!
Task 2: Get One Specific Post
curl https://jsonplaceholder.typicode.com/posts/1
Task 3: Create a New Post
curl -X POST https://jsonplaceholder.typicode.com/posts \
-H "Content-Type: application/json" \
-d '{"title":"My First Post","body":"Hello World","userId":1}'
Response:
{
"title": "My First Post",
"body": "Hello World",
"userId": 1,
"id": 101
}
The API assigned it ID 101! (It's not actually saved since this is a test API, but it simulates the real thing)
Complete Flow Diagram: What Happens When You Use cURL
┌──────────────────────────────────────────────────────────┐
│ 1. You type in terminal: │
│ curl -X POST https://api.example.com/users \ │
│ -H "Content-Type: application/json" \ │
│ -d '{"name":"John"}' │
└──────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ 2. cURL builds the HTTP request: │
│ ┌──────────────────────────────────────┐ │
│ │ POST /users HTTP/1.1 │ │
│ │ Host: api.example.com │ │
│ │ Content-Type: application/json │ │
│ │ │ │
│ │ {"name":"John"} │ │
│ └──────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ 3. Request travels over internet to server │
│ [Your Computer] ═══════════► [api.example.com] │
└──────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ 4. Server processes request: │
│ ✓ Checks if data is valid │
│ ✓ Creates new user in database │
│ ✓ Generates user ID │
└──────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ 5. Server sends response: │
│ ┌──────────────────────────────────────┐ │
│ │ HTTP/1.1 201 Created │ │
│ │ Content-Type: application/json │ │
│ │ │ │
│ │ {"id":123,"name":"John"} │ │
│ └──────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ 6. cURL displays response in your terminal: │
│ {"id":123,"name":"John"} │
└──────────────────────────────────────────────────────────┘
Conclusion: You're Ready to Start!
You now know:
✅ What cURL is and why it's useful
✅ How to make basic GET requests
✅ How to understand responses and status codes
✅ How to send data with POST requests
✅ Common mistakes to avoid
✅ How to test real APIs
Happy cURL-ing! 🚀
Useful Resources:
JSONPlaceholder (practice API): https://jsonplaceholder.typicode.com
cURL documentation: https://curl.se/docs/
HTTP status codes reference: https://httpstatuses.com
