API Basics: What Are APIs and Why They MatterLesson 1.2

Understanding HTTP: The Foundation of REST APIs

HTTP protocol, HTTP request, HTTP response, headers, body, URL structure, query parameters, path parameters

Understanding HTTP: The Foundation of REST APIs

REST APIs are built on top of HTTP (HyperText Transfer Protocol), the same protocol your browser uses to load web pages. Before you can design or build a REST API, you need to understand what an HTTP request and response look like and what information they carry.

DiagramHTTP Request and Response Structure

IMAGE PROMPT (replace this block with your generated image):

Flat developer diagram on white background. Title: HTTP Request and Response Structure. Two columns side by side with a vertical divider. Left column header: HTTP Request (header in #3A5EFF). Inside: three labeled rows — Row 1: Request Line showing POST /api/users HTTP/1.1. Row 2: Headers showing Content-Type: application/json and Authorization: Bearer token. Row 3: Body (optional) showing a small JSON snippet {name, email}. Right column header: HTTP Response (header in #3A5EFF). Inside: Row 1: Status Line showing 201 Created. Row 2: Headers showing Content-Type: application/json. Row 3: Body showing {id:1, name, email}. Between both columns place a horizontal double-headed arrow labeled HTTP Exchange. Clean monospace font for code snippets, sans-serif for labels, brand color #3A5EFF for headers and arrows, white background.

The Structure of an HTTP Request

Every HTTP request has three parts: a request line, headers, and an optional body. The request line contains the HTTP method (GET, POST, etc.), the path (/users/42), and the HTTP version (HTTP/1.1). Headers are key-value pairs that carry metadata about the request — things like the content type, authorization tokens, and the client's accepted response formats. The body carries data sent to the server, typically in POST, PUT, and PATCH requests.

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGci...

{
  "name": "Bob Smith",
  "email": "bob@example.com"
}

The Structure of an HTTP Response

An HTTP response also has three parts: a status line, headers, and a body. The status line contains the HTTP version and a status code (200, 404, 500, etc.) along with a reason phrase. Response headers describe the content type, cache behavior, and security policies. The body contains the data returned to the client — usually a JSON object or array.

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/99

{
  "id": 99,
  "name": "Bob Smith",
  "email": "bob@example.com"
}

URL Structure and Resource Paths

In REST APIs, URLs represent resources — the nouns of your API. A well-designed REST API URL clearly communicates what resource is being accessed. URLs follow a hierarchy: https://api.example.com/v1/users/42/orders. Breaking this down: https://api.example.com is the base URL, /v1 is the API version, /users is the resource collection, /42 is the specific user ID (a path parameter), and /orders is a nested resource belonging to that user.

Path Parameters vs Query Parameters

Path parameters identify a specific resource: /users/42 retrieves user with ID 42. Query parameters filter, sort, or paginate a collection and are appended after a question mark: /users?role=admin&page=2&limit=20. Use path parameters for identification and query parameters for modification of the result set.

Common HTTP Headers

Content-Type: application/json tells the server the format of the request body. Accept: application/json tells the server what format the client expects in the response. Authorization: Bearer token carries authentication credentials. Cache-Control manages caching behavior. Understanding these headers is essential for building correct, secure APIs.