Status Codes, Parameters, and Authentication

You now know how to make API calls with cURL and Postman. In this module, we go deeper into three critical topics that every API developer must master: status codes (understanding what the server is telling you), parameters (filtering and targeting data), and authentication (proving who you are).

These are the skills that separate someone who can follow a tutorial from someone who can confidently work with any API in the real world.

---

1. HTTP Status Codes: The Complete Guide

Every HTTP response includes a status code — a three-digit number that tells you exactly what happened with your request. Learning to read status codes is like learning to read a doctor's chart. It instantly tells you the health of your API interaction.

The Five Categories

graph LR
    A[Status Codes] --> B["1xx<br/>Informational"]
    A --> C["2xx<br/>Success"]
    A --> D["3xx<br/>Redirection"]
    A --> E["4xx<br/>Client Error"]
    A --> F["5xx<br/>Server Error"]

    style B fill:#6b7280,color:#fff
    style C fill:#059669,color:#fff
    style D fill:#0891b2,color:#fff
    style E fill:#d97706,color:#fff
    style F fill:#dc2626,color:#fff

Success Codes (2xx)

These mean your request was processed successfully:

Code	Name	Meaning	When You See It
200	OK	Request succeeded	GET, PUT, PATCH responses
201	Created	Resource was created	POST response
204	No Content	Success, but nothing to return	DELETE response
202	Accepted	Request accepted, processing later	Async operations

200 OK Example:

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

HTTP/2 200
content-type: application/json; charset=utf-8

{"userId":1,"id":1,"title":"sunt aut facere..."}

201 Created Example:

curl -i -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "New Post", "body": "Content", "userId": 1}'

HTTP/2 201
content-type: application/json; charset=utf-8

{"title":"New Post","body":"Content","userId":1,"id":101}

Client Error Codes (4xx)

These mean you made a mistake. The problem is with your request:

Code	Name	Meaning	Common Cause
400	Bad Request	Invalid request data	Malformed JSON, missing fields
401	Unauthorized	Not authenticated	Missing or expired token
403	Forbidden	Authenticated but not allowed	Insufficient permissions
404	Not Found	Resource does not exist	Wrong URL or deleted resource
405	Method Not Allowed	Wrong HTTP method	POST to a GET-only endpoint
409	Conflict	Conflicts with current state	Duplicate entry
422	Unprocessable Entity	Data format OK but values invalid	Email without @ symbol
429	Too Many Requests	Rate limit exceeded	Making too many calls

400 Bad Request Example:

When you send invalid JSON:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John"'  # Missing closing brace

Response:

{
  "error": "Bad Request",
  "message": "Invalid JSON in request body"
}

401 Unauthorized Example:

When you forget the authentication token:

curl https://api.example.com/protected/data

Response:

{
  "error": "Unauthorized",
  "message": "Authentication token is required"
}

404 Not Found Example:

curl -i https://jsonplaceholder.typicode.com/posts/99999

This returns a 404 because post 99999 does not exist.

429 Too Many Requests Example:

When you exceed the rate limit:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "retry_after": 60
}

Server Error Codes (5xx)

These mean the server had a problem. It is not your fault:

Code	Name	Meaning	What To Do
500	Internal Server Error	Server crashed	Report to API provider
502	Bad Gateway	Upstream server error	Wait and retry
503	Service Unavailable	Server overloaded or maintenance	Wait and retry
504	Gateway Timeout	Upstream server too slow	Wait and retry

The key distinction:

• 4xx = Fix your request (your problem)
• 5xx = Wait and retry, or contact support (their problem)

Status Code Decision Flowchart

graph TD
    A[Got a Response?] -->|Yes| B{Status Code?}
    A -->|No| N[Connection Error<br/>Check URL and internet]
    
    B -->|2xx| C[Success!<br/>Parse the response body]
    B -->|400| D[Bad Request<br/>Check your JSON and required fields]
    B -->|401| E[Unauthorized<br/>Check your auth token]
    B -->|403| F[Forbidden<br/>Check your permissions]
    B -->|404| G[Not Found<br/>Check the URL and resource ID]
    B -->|422| H[Validation Error<br/>Check field values]
    B -->|429| I[Rate Limited<br/>Wait and retry]
    B -->|500| J[Server Error<br/>Not your fault - retry later]
    B -->|503| K[Service Down<br/>Wait for maintenance to end]

    style C fill:#059669,color:#fff
    style D fill:#d97706,color:#fff
    style E fill:#d97706,color:#fff
    style F fill:#d97706,color:#fff
    style G fill:#d97706,color:#fff
    style J fill:#dc2626,color:#fff
    style K fill:#dc2626,color:#fff

---

2. Query Parameters

Query parameters filter, sort, search, and paginate data. They are appended to the URL after a ? symbol, with multiple parameters separated by &.

Syntax

https://api.example.com/resource?key1=value1&key2=value2&key3=value3

Common Uses

Purpose	Example
Filtering	?status=active
Searching	?q=laptop
Sorting	?sort=price&order=asc
Pagination	?page=2&limit=20
Field selection	?fields=name,email
Date range	?from=2026-01-01&to=2026-02-22

Real Examples with JSONPlaceholder

Filter posts by user:

curl "https://jsonplaceholder.typicode.com/posts?userId=1"

This returns only the 10 posts created by user 1, instead of all 100 posts.

Filter comments by post:

curl "https://jsonplaceholder.typicode.com/comments?postId=1"

Multiple filters:

curl "https://jsonplaceholder.typicode.com/todos?userId=1&completed=true"

This returns only completed todos for user 1.

Pagination

Most APIs return large collections in pages:

# Page 1 with 10 items per page
curl "https://api.example.com/products?page=1&limit=10"

# Page 2 with 10 items per page
curl "https://api.example.com/products?page=2&limit=10"

# Page 3 with 25 items per page
curl "https://api.example.com/products?page=3&limit=25"

A typical paginated response includes metadata:

{
  "data": [
    {"id": 11, "name": "Product 11"},
    {"id": 12, "name": "Product 12"}
  ],
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 100,
    "totalPages": 10,
    "hasNext": true,
    "hasPrev": true
  }
}

---

3. Path Parameters

Path parameters identify a specific resource within the URL path. They are part of the URL structure itself, not appended after ?.

Syntax

https://api.example.com/users/:id
https://api.example.com/users/42

The :id is a placeholder that gets replaced with an actual value (like 42).

Examples

# Get user 1
curl https://jsonplaceholder.typicode.com/users/1

# Get post 5
curl https://jsonplaceholder.typicode.com/posts/5

# Get user 3's posts
curl https://jsonplaceholder.typicode.com/users/3/posts

# Get comment 10 on post 2
curl https://jsonplaceholder.typicode.com/posts/2/comments

Path vs Query Parameters: When to Use Each

graph TD
    A[Need to identify a resource?] -->|Yes| B[Path Parameter<br/>/users/42]
    A -->|No| C[Need to filter or modify results?]
    C -->|Yes| D[Query Parameter<br/>/users?role=admin]
    C -->|No| E[Just request the collection<br/>/users]

    style B fill:#4f46e5,color:#fff
    style D fill:#059669,color:#fff
    style E fill:#0891b2,color:#fff

Question	Answer	Use
Which user?	User 42	Path: /users/42
Which users?	Active ones	Query: /users?status=active
Which post?	Post 7	Path: /posts/7
Whose posts?	User 3's posts	Path: /users/3/posts
How many?	20 per page	Query: /posts?limit=20
In what order?	By date, newest first	Query: /posts?sort=date&order=desc

Rule of thumb:

• Path parameters = identify a specific resource
• Query parameters = filter, sort, search, or paginate a collection

---

4. API Authentication

Most real-world APIs require you to prove who you are before granting access. This is called authentication (who are you?) and authorization (what are you allowed to do?).

Why Authentication Exists

Without authentication:

• Anyone could read your private data
• Anyone could modify or delete resources
• APIs could not track usage or enforce rate limits
• There would be no way to bill for API usage

Common Authentication Methods

graph TD
    A[API Authentication Methods] --> B[API Keys]
    A --> C[Bearer Tokens - JWT]
    A --> D[Basic Auth]
    A --> E[OAuth 2.0]

    B --> B1["Simple key-value<br/>Header or query param"]
    C --> C1["Token-based<br/>Most common for modern APIs"]
    D --> D1["Username:Password<br/>Base64 encoded"]
    E --> E1["Delegated access<br/>Third-party login"]

    style A fill:#4f46e5,color:#fff
    style B fill:#0891b2,color:#fff
    style C fill:#0891b2,color:#fff
    style D fill:#0891b2,color:#fff
    style E fill:#0891b2,color:#fff

Method 1: API Keys

The simplest form of authentication. You get a unique key and include it with every request.

In a Header:

curl -H "X-API-Key: abc123def456" \
  https://api.example.com/data

In a Query Parameter:

curl "https://api.example.com/data?api_key=abc123def456"

How to get an API key:

1. Sign up on the API provider's website
2. Navigate to their developer dashboard
3. Create a new API key
4. Copy and use it in your requests

Pros: Simple, easy to implement Cons: If leaked, anyone can use your key; no expiration by default

Method 2: Bearer Tokens (JWT)

JWT (JSON Web Token) is the most common authentication method for modern REST APIs. A token is a long, encoded string that contains your identity information.

How it works:

sequenceDiagram
    participant Client
    participant Auth as Auth Server
    participant API as API Server

    Client->>Auth: POST /login with credentials
    Auth-->>Client: JWT Token
    Client->>API: GET /data with Bearer token
    API->>API: Validate token
    API-->>Client: 200 OK with data

Step 1: Get a token (login)

curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjQyLCJyb2xlIjoiYWRtaW4iLCJleHAiOjE3MDg2NDAwMDB9.abc123",
  "expiresIn": 3600
}

Step 2: Use the token

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.example.com/users/me

In Postman:

1. Go to the Authorization tab
2. Select Bearer Token
3. Paste your token
4. Postman adds the header automatically

Pros: Stateless, self-contained, expires automatically Cons: More complex to implement; tokens can be long

What is Inside a JWT?

A JWT has three parts separated by dots:

eyJhbGci.eyJ1c2Vy.abc123
  Header   Payload  Signature

The payload (middle part) contains encoded JSON:

{
  "userId": 42,
  "role": "admin",
  "exp": 1708640000
}

This is encoded (Base64), not encrypted. Anyone can read the payload. The signature verifies it has not been tampered with.

Method 3: Basic Authentication

The oldest and simplest method. You send a username and password with every request, encoded in Base64.

curl -u username:password https://api.example.com/data

cURL's -u flag automatically encodes the credentials and sends them in the Authorization: Basic header.

Equivalent manual header:

# Base64 of "username:password" is "dXNlcm5hbWU6cGFzc3dvcmQ="
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  https://api.example.com/data

In Postman:

1. Go to Authorization tab
2. Select Basic Auth
3. Enter username and password

Pros: Very simple Cons: Password sent with every request; must use HTTPS

Method 4: OAuth 2.0 (Overview)

OAuth 2.0 is used when you want to access a user's data on a third-party service without knowing their password. For example, "Sign in with Google" uses OAuth 2.0.

The flow is more complex and involves redirecting the user to the third-party service for approval. This is beyond the scope of this beginner course, but you should know it exists and is used by major APIs like Google, GitHub, Facebook, and Spotify.

Authentication Comparison

Method	Complexity	Security	Best For
API Key	Low	Medium	Simple APIs, server-to-server
Bearer (JWT)	Medium	High	Web/mobile apps, user authentication
Basic Auth	Low	Low	Internal tools, HTTPS-only
OAuth 2.0	High	Very High	Third-party integrations

---

5. Putting It All Together: Real-World API Example

Let us walk through a complete real-world API interaction that uses status codes, parameters, and authentication together.

Scenario: Working with the GitHub API

The GitHub API is a real, public REST API that demonstrates all these concepts.

Step 1: Public endpoint (no auth required)

# Get information about a GitHub user
curl https://api.github.com/users/octocat

Response (200 OK):

{
  "login": "octocat",
  "id": 583231,
  "name": "The Octocat",
  "company": "@github",
  "public_repos": 8,
  "followers": 12000
}

Step 2: Using query parameters to search

# Search for repositories
curl "https://api.github.com/search/repositories?q=rest+api&sort=stars&order=desc&per_page=5"

This searches for repos matching "rest api", sorted by stars, showing 5 results per page.

Step 3: Authenticated request (more data, higher rate limits)

# With a personal access token
curl -H "Authorization: Bearer ghp_your_token_here" \
  https://api.github.com/user/repos

Without authentication, GitHub allows 60 requests per hour. With a token, you get 5,000 requests per hour.

Step 4: Handling rate limits

# Check your rate limit status
curl -i https://api.github.com/rate_limit

Response headers include:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1708640000

---

6. Common Authentication Mistakes

Mistake	Symptom	Fix
Missing Bearer prefix	401 Unauthorized	Use Authorization: Bearer TOKEN not just Authorization: TOKEN
Expired token	401 Unauthorized	Get a new token
Wrong header name	401 Unauthorized	Check the API docs for the exact header name
Token in wrong place	401 Unauthorized	Some APIs use header, others use query param
No HTTPS	Credentials intercepted	Always use https://

---

Summary and Key Takeaways

1. Status codes instantly tell you the result: 2xx success, 4xx your error, 5xx server error.
2. 400 means bad request data; 401 means missing auth; 404 means not found; 500 means server problem.
3. Path parameters identify specific resources: /users/42.
4. Query parameters filter and modify results: ?status=active&sort=name.
5. API Keys are simple but limited; JWT Bearer Tokens are the modern standard.
6. Always send authentication tokens in the Authorization header.
7. Monitor rate limits to avoid getting blocked.
8. Always use HTTPS when sending credentials.

---

Lesson Review Quiz

---

Practice Exercise

1. Status Code Exploration: Run these cURL commands and note the status codes:

# Should return 200
curl -s -o /dev/null -w "%{http_code}" https://jsonplaceholder.typicode.com/posts/1

# Should return 404
curl -s -o /dev/null -w "%{http_code}" https://jsonplaceholder.typicode.com/posts/99999

# Should return 201
curl -s -o /dev/null -w "%{http_code}" -X POST \
  https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"Test","body":"Content","userId":1}'

2. Query Parameters Practice:

# Get only user 1's posts
curl "https://jsonplaceholder.typicode.com/posts?userId=1"

# Get only completed todos for user 2
curl "https://jsonplaceholder.typicode.com/todos?userId=2&completed=true"

3. GitHub API Exploration (no auth needed):

# Get a user's profile
curl https://api.github.com/users/octocat

# Search for repositories
curl "https://api.github.com/search/repositories?q=javascript&sort=stars&per_page=3"

# Check rate limit headers
curl -i https://api.github.com/rate_limit

In the final module, we will bring everything together with a REST API design exercise, debugging guide, and final project.