HTTP in the Wild: APIs and REST

Discover what happens when HTTP drops the HTML costume. Learn how APIs expose the raw business logic of the web and how REST makes everything predictable.

What’s an API?

An API is an endpoint (a URL) that responds to HTTP requests with structured data in the response body that is designed to be read by programs, not people.

In a modern context, this structured data almost always takes the form of JSON - a plain text format that stores key-value pairs, often in nested objects or arrays. JSON was designed to be both machine-parseable and still human-readable, which makes it ideal for APIs.

That’s it. That's an API. Same language. Same requests. Just a different kind of response.

You’ve already talked to servers — logging in, posting forms, submitting data. The only difference with APIs is that you’re not asking for a web page or a CSS file or an image, you’re asking for structured data.

Note that HTML isn’t what we mean by "structured data", it’s for rendering. Same with images, CSS, and PDFs. They're for human eyes, not programmatic logic.

What's Really Going On

Load almost any modern website - Twitter, Gmail, Instagram - and watch the Network tab. See all those requests to api endpoints? Those aren't fetching web pages. They're fetching data.

Here's the same user profile, two ways:

The Browser Way:

HTTP/1.1 200 OK
Content-Type: text/html

<html>
  <body>
    <h1>Alice's Profile</h1>
    <p>Member since: 2020</p>
  </body>
</html>

The API Way:

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

{
  "id": 12345,
  "username": "alice",
  "email": "alice@example.com",
  "created_at": "2020-01-15T08:30:00Z",
  "role": "user"
}

Same user. Same HTTP. Different response format.

APIs: HTTP for Machines

An API (Application Programming Interface) is just an HTTP endpoint that returns structured data instead of formatted web pages. That's it. No magic.

The key difference: APIs are designed for programs to consume, not people to read. This means:

  • Structured data (same format every time)
  • Machine-parseable (programs can understand it)
  • No presentation layer (just the raw information)

JSON: The Language of APIs

APIs needed a format that was:

  • Human-readable (for debugging)
  • Machine-parseable (for automation)
  • Lighter than XML (less verbose)

Enter JSON (JavaScript Object Notation):

{
  "name": "Alice",
  "age": 30,
  "roles": ["user", "moderator"],
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

Objects (curly braces), arrays (square brackets), key-value pairs. That's JSON. It won because it's simple.

Remember Content-Type from Lesson 4? APIs rely on it:

  • Send Content-Type: application/json with JSON data
  • Expect Content-Type: application/json in response
  • The server uses this header to know how to parse your request

REST: A Design Philosophy

REST (Representational State Transfer) isn't a protocol - it's a set of conventions that make APIs predictable. Most web APIs follow REST principles because predictability helps both developers and users.

REST treats everything as a resource (users, posts, comments) and uses HTTP methods to indicate actions:

The REST Pattern

  • List all users: GET /api/users → Returns array of users
  • Get one user: GET /api/users/123 → Returns single user
  • Create user: POST /api/users → Creates new user
  • Update user: PUT /api/users/123 → Replaces entire user
  • Tweak user: PATCH /api/users/123 → Updates specific fields
  • Delete user: DELETE /api/users/123 → Removes user

This consistency is powerful. Once you know one endpoint, you can often guess others:

  • Found /api/users? Try /api/posts, /api/comments
  • See /api/v1/users? Check if /api/v2/users exists

Status Codes Matter More

In APIs, status codes carry real meaning because programs make decisions based on them:

response = requests.get('/api/users/999999')
if response.status_code == 404:
    print("User doesn't exist")
elif response.status_code == 401:
    print("Need to log in first")

Common API status codes:

  • 200 OK: Here's your data
  • 201 Created: I made what you asked for
  • 204 No Content: Done, but nothing to return
  • 400 Bad Request: Your request is malformed
  • 401 Unauthorized: Missing or invalid credentials
  • 403 Forbidden: Valid credentials, but no permission
  • 404 Not Found: Resource doesn't exist
  • 429 Too Many Requests: Rate limit exceeded

Working with APIs

Authentication

Web apps typically use cookies for authentication. APIs often use different approaches:

# API Key in header
curl -H "X-API-Key: your-api-key" https://api.example.com/data

# Bearer token (common with OAuth)
curl -H "Authorization: Bearer your-token-here" https://api.example.com/data

Each API documents its authentication method. Always send credentials in headers or request bodies, never in URLs where they might be logged.

Pagination

APIs can't return unlimited data at once, so they often paginate:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 100,
    "total": 10000,
    "next": "/api/users?page=2"
  }
}

This prevents overwhelming both the server and your application with too much data at once.

Rate Limiting

Most APIs limit how many requests you can make:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

These headers tell you:

  • How many requests you're allowed
  • How many you have left
  • When the limit resets

Respect these limits - exceeding them usually results in temporary bans.

APIs in Modern Web Apps

Here's something crucial: most modern web applications are built on APIs.

Open DevTools on any Single Page Application:

  1. The first request loads HTML and JavaScript
  2. Every subsequent action triggers API calls
  3. JavaScript renders the responses into what you see

This architecture means:

  • The API contains all the functionality
  • The web interface is just one client among many
  • Mobile apps use the same API
  • You can too

Finding APIs

Many sites expose their APIs:

# Common API documentation paths
/api
/api/docs
/swagger.json
/openapi.json

# WordPress sites have a standard API
/wp-json/wp/v2/posts

# Many sites follow patterns
/api/v1/
/api/v2/

Developer tools are your friend here - watch the Network tab to see what APIs a site uses internally.

Beyond REST

While REST dominates, other API styles exist:

  • GraphQL: Instead of multiple endpoints, one endpoint where you query for exactly the data you need. More flexible but more complex.
  • WebSockets: For real-time, bidirectional communication. Different protocol built on top of HTTP.
  • gRPC: Binary protocol using HTTP/2. Faster but harder to debug.

For now, focus on REST - it's everywhere and its patterns apply broadly.

Try It Yourself

You already have the tools:

# GitHub's public API (no auth needed)
curl https://api.github.com/users/github

# See the same data in your browser
# https://api.github.com/users/github

# Parse it with Python
import requests
response = requests.get('https://api.github.com/users/github')
data = response.json()
print(f"GitHub has {data['public_repos']} public repos")

APIs are everywhere. News sites, weather services, social media platforms - most offer APIs. Now you know how to speak their language.

What You've Learned

APIs are simply HTTP endpoints that return structured data. They follow predictable patterns (especially REST APIs) and use standard formats like JSON. Every modern web application is built on APIs, and now you can interact with them directly.

You understand:

  • APIs are HTTP with structured responses
  • REST provides consistent patterns
  • JSON is the common language
  • Status codes and headers matter more
  • Authentication often uses tokens instead of cookies

The web isn't just pages anymore. It's a rich ecosystem of APIs, and you speak their language.