Understanding How APIs Work — Complete Guide

In this tutorial, you will learn about Understanding How APIs Work. We cover key concepts, practical examples, and best practices to help you master this topic.

To write great API documentation, you must understand how APIs work under the hood including HTTP methods, status codes, request-response cycle, REST resource naming, authentication patterns, pagination, and error handling conventions.

What You'll Learn

The HTTP protocol basics every API writer needs, the difference between REST and Graphql, how request and response cycle works, common authentication patterns, status code categories, pagination approaches, and what developers expect from each API pattern.

Why It Matters

You cannot document what you do not understand. Writers who understand HTTP methods, status codes, and authentication write accurate, complete documentation. Writers who do not understand these basics produce confusing, incomplete, and sometimes incorrect documentation.

Real-World Use

The DodaTech documentation team requires every writer to complete an API fundamentals course before writing a single doc. They make actual API calls, read real responses, and debug real errors. This hands-on experience produces documentation that developers trust because it reflects real API behavior.

HTTP Methods

flowchart TD
  A[HTTP Methods] --> B[GET - Read]
  A --> C[POST - Create]
  A --> D[PUT - Replace]
  A --> E[PATCH - Update]
  A --> F[DELETE - Remove]
  B --> G[Safe, idempotent, cached]
  C --> H[Not safe, not idempotent]
  D --> I[Idempotent, replaces resource]
  E --> J[Partial update]
  F --> K[Idempotent, removes resource]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

HTTP Status Codes

Status codes tell developers whether their request succeeded and how to handle the response.

Request-Response Cycle

Every API call follows the same cycle. Document each step.

sequenceDiagram
  participant D as Developer
  participant API as API Server
  participant DB as Database

  D->>API: HTTP Request (method, URL, headers, body)
  API->>API: Validate authentication
  API->>API: Validate parameters and body
  API->>DB: Query or write data
  DB-->>API: Result
  API->>API: Format response
  API-->>D: HTTP Response (status, headers, body)

# Complete request example showing the cycle
import requests

# Step 1: Prepare request
url = "https://api.dodatech.com/v2/files"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}

# Step 2: Send request
response = requests.get(url, headers=headers)

# Step 3: Handle response
print(f"Status: {response.status_code}")
print(f"Body: {response.json()}")

# Expected output:
# Status: 200
# Body: {'data': [...], 'pagination': {...}}

REST Resource Naming

REST APIs organize resources with consistent URL patterns.

## REST Naming Conventions

| Pattern | Example | Meaning |
|---------|---------|---------|
| GET /resources | GET /files | List all files |
| GET /resources/{id} | GET /files/abc123 | Get one file |
| POST /resources | POST /files | Create a file |
| PUT /resources/{id} | PUT /files/abc123 | Replace a file |
| PATCH /resources/{id} | PATCH /files/abc123 | Update part of a file |
| DELETE /resources/{id} | DELETE /files/abc123 | Delete a file |

Resources use plural nouns. Actions use HTTP methods, not verbs in URLs.

Authentication Patterns

The three most common authentication patterns you will document.

# Pattern 1: API Key in header
curl -H "Authorization: Bearer YOUR_KEY" https://api.example.com/data

# Pattern 2: Basic Auth
curl -u username:password https://api.example.com/data

# Pattern 3: OAuth 2.0 Bearer Token
curl -H "Authorization: Bearer ACCESS_TOKEN" https://api.example.com/data

Pagination

Most APIs paginate list responses. Document the pagination method clearly.

// Page-based pagination
{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  }
}

// Cursor-based pagination
{
  "data": [...],
  "next_cursor": "abc123",
  "has_more": true
}

Common Mistakes

1. Confusing HTTP Methods

Documenting POST when the API uses PUT, or GET when it uses DELETE. Always verify the actual HTTP method before writing.

2. Wrong Status Code Documentation

Documenting 200 when the API returns 201 for creation, or 404 when it returns 400 for bad requests. Verify every status code by testing.

3. No Authentication Context

Listing endpoints without authentication requirements. Document which auth method each endpoint uses and what scopes are needed.

4. Assuming All APIs Are REST

Documenting a non-REST API (GraphQL, gRPC, SOAP) with REST conventions. Understand the API paradigm before writing.

5. Ignoring Rate Limits

Not documenting rate limits leaves developers to discover them through 429 errors. Always document limits.

6. Mixing Up Idempotent and Non-Idempotent Methods

Documenting GET as unsafe (it is safe) or POST as idempotent (it is not). Understand idempotency for each HTTP method.

7. No Versioning Context

Documenting endpoints without version prefixes and versioning strategy. Developers need to know which version they are using.

Practice Questions

1. What are the four categories of HTTP status codes?

2xx Success, 3xx Redirection, 4xx Client Error, and 5xx Server Error. Each category tells the developer whether the issue is on their side or the API provider's side.

2. What is the difference between PUT and PATCH?

PUT replaces the entire resource. PATCH updates only the specified fields. PUT is idempotent (same result every time), PATCH may not be idempotent.

3. Why is GET considered a safe method?

GET does not change server state. It only retrieves data. Safe methods can be cached, retried automatically, and should not have side effects.

4. What is the difference between page-based and cursor-based pagination?

Page-based uses page numbers and is simpler. Cursor-based uses opaque cursor strings and is more stable when new items are added during iteration.

5. Challenge: Make 5 different API calls to a public API (GET, POST, PUT, PATCH, DELETE if available) and document each one including the HTTP method, URL, headers, request body, response body, and status code.

FAQ

Mini Project: API HTTP Reference

Create a reference card documenting the HTTP methods, status code categories, authentication patterns, and pagination types used by a real API. Include examples of each. This reference card will guide your documentation writing for all future API docs.

What's Next

Now that you understand how APIs work, learn to write clear Writing Endpoint Descriptions. Then dive into Writing Parameter Descriptions.