API Fundamentals

HTTP Methods

Method Purpose Example

GET

Retrieve data

curl api.example.com/users

POST

Create resource

curl -X POST -d '{"name":"John"}' …​

PUT

Replace resource

curl -X PUT -d '{"name":"Jane"}' …​/users/1

PATCH

Partial update

curl -X PATCH -d '{"email":"new@x.com"}' …​

DELETE

Remove resource

curl -X DELETE …​/users/1

Request Anatomy

GET /api/v1/users?status=active HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
Accept: application/json

{"filter": "active"}

Components:

Part Description

Method + Path

GET /api/v1/users

Query Params

?status=active&limit=10

Headers

Metadata (auth, content type)

Body

Payload (POST/PUT/PATCH)

Status Codes

Code Category Meaning

200

Success

OK - request succeeded

201

Success

Created - resource created

204

Success

No Content - success, empty response

400

Client Error

Bad Request - malformed request

401

Client Error

Unauthorized - auth required

403

Client Error

Forbidden - auth valid but access denied

404

Client Error

Not Found - resource doesn’t exist

422

Client Error

Unprocessable - validation failed

429

Client Error

Too Many Requests - rate limited

500

Server Error

Internal Server Error

502

Server Error

Bad Gateway

503

Server Error

Service Unavailable

Common Headers

Request Headers

# Authentication
-H "Authorization: Bearer TOKEN"
-H "X-API-Key: YOUR_KEY"

# Content type (what you're sending)
-H "Content-Type: application/json"
-H "Content-Type: application/x-www-form-urlencoded"

# Accept (what you want back)
-H "Accept: application/json"

# Custom headers (varies by API)
-H "X-Request-ID: uuid-here"

Response Headers

# View response headers
curl -sI https://api.example.com/users

# Common response headers
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-Request-Id: abc123

curl Basics

# Silent mode (no progress bar)
curl -s https://api.example.com/data

# Include headers in output
curl -sI https://api.example.com/data

# Verbose (debug)
curl -v https://api.example.com/data

# Follow redirects
curl -sL https://api.example.com/data

# POST with JSON body
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "test"}' \
  https://api.example.com/users

# POST with data from file
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d @payload.json \
  https://api.example.com/users

Practice: JSONPlaceholder

# GET - list users
curl -s https://jsonplaceholder.typicode.com/users | jq

# GET - single user
curl -s https://jsonplaceholder.typicode.com/users/1 | jq

# POST - create (simulated)
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"title": "foo", "body": "bar", "userId": 1}' \
  https://jsonplaceholder.typicode.com/posts | jq

# GET with query params
curl -s "https://jsonplaceholder.typicode.com/posts?userId=1" | jq

Exercises

  1. Fetch all posts from JSONPlaceholder, count them with jq

  2. Get user 3’s email address only

  3. Create a new post, capture the returned ID

  4. Fetch posts for user 1, extract just titles