4. HTTP basics: requests, URLs, REST

Every API conversation happens using HTTP, the same protocol your browser uses to load web pages. The next four sections open up the protocol: the shape of a request, the anatomy of a URL, what REST actually means, and how resource-based URLs work in practice.

The request-response pattern

Every HTTP interaction is two parties having a structured conversation. You ask, the server answers. Here's a real example, the raw HTTP message that gets sent behind the scenes when your code makes an API request:

GET /weather?city=London HTTP/1.1
Host: api.example-weather.com
Accept: application/json

You'll never write this yourself, but understanding its shape helps you see what's really happening when you call requests.get() later. Each line has a job:

• GET /weather?city=London HTTP/1.1: the request line with the method (GET), path (/weather), parameters (?city=London), and protocol version (HTTP/1.1)
• Host: api.example-weather.com: a header telling the server which domain this request is for
• Accept: application/json: a header saying "I want JSON back, not HTML or XML"

The server reads the request and sends back a response with the same kind of shape:

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

{
  "city": "London",
  "temperature": 12,
  "conditions": "Cloudy",
  "humidity": 75
}

The response splits into three parts:

• Status code (200): did it work? 200 means success
• Headers (Content-Type): metadata about the response
• Body (the JSON data): the actual information you requested

URLs: addresses for everything

Every API request goes to a specific URL, a unique address for a specific resource or action. The pieces of a URL each carry meaning:

https://api.example-weather.com/v1/forecast?city=London&units=metric
│       │                      │  │        │
│       │                      │  │        └─ Parameters (details)
│       │                      │  │
│       │                      │  └─ Resource (what you want)
│       │                      └─ Version (which API version)
│       └─ Domain (which service)
└─ Protocol (how to communicate)

Think of URLs like addresses. The domain is the city (London), the path is the street and building (/10 Downing Street), and the parameters are specific instructions (Ring doorbell, ask for the Prime Minister).

The same pattern appears across every API you'll meet:

# Weather API
https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_KEY

# GitHub API
https://api.github.com/users/octocat/repos

# Spotify API
https://api.spotify.com/v1/search?q=Beatles&type=artist

# REST Countries API
https://restcountries.com/v3.1/name/canada

Every URL points to a specific resource and may include parameters to customise the request. This consistency makes APIs predictable. Once you understand one API, you understand the general structure of all APIs.

What "REST API" means

REST stands for Representational State Transfer, but that formal definition doesn't help anyone understand it. Here's what it actually means in practice.

REST is a set of design principles for building web APIs. When an API follows these principles, we call it RESTful. The term was coined in 2000 by Roy Fielding in his doctoral dissertation, and it's become the dominant way to design modern web APIs.

RESTful APIs share five characteristics:

• Resource-based URLs: each resource has a clear URL. /users/123 represents user 123. /products/456 represents product 456.
• HTTP methods indicate actions: GET retrieves data, POST creates it, PUT updates it, DELETE removes it. The same URL (/users/123) does different things depending on the HTTP method.
• Stateless communication: each request contains everything the server needs to understand it. The server doesn't remember previous requests. The next page covers why this matters.
• Standard status codes: 200 means success, 404 means not found, 401 means unauthorized. These codes have consistent meanings across all RESTful APIs.
• JSON responses: most modern RESTful APIs return data in JSON format, which is easy to parse and work with.

The vast majority of public APIs follow REST-style principles. When you learn to work with one RESTful API, you've learned fundamental patterns that apply to thousands of others. OpenWeatherMap, GitHub, Stripe, and Spotify all use RESTful design. You don't need to memorise the principles or worry about implementing them perfectly. As a developer consuming APIs (not building them), you just need to recognise the patterns: resources have URLs, actions use HTTP methods, responses use standard status codes. That's REST in practice.

Some APIs aren't RESTful. GraphQL, SOAP, and RPC-style APIs exist too. But REST is by far the most common approach you'll encounter. When someone says "I'm working with the GitHub API," they usually mean the RESTful GitHub API.

Resource-based URLs

Look at that first principle in action. REST APIs organise everything around resources, and each resource gets its own clean, predictable URL:

# All of an artist's albums
https://api.spotify.com/v1/artists/6vWDO969PvNqNYHIOW5v0m/albums

# A specific album
https://api.spotify.com/v1/albums/4aawyAB9vmqN3uQ7FjRGTy

# The tracks inside that album
https://api.spotify.com/v1/albums/4aawyAB9vmqN3uQ7FjRGTy/tracks

# A specific user's playlists
https://api.spotify.com/v1/users/spotify/playlists

# A specific playlist's tracks
https://api.spotify.com/v1/playlists/37i9dQZF1DXcBWIGoYBM5M/tracks

Combine resource-based URLs with HTTP methods, and you get a complete system for working with data:

The URL identifies what you're working with (the resource), and the HTTP method identifies what you want to do with it (the action). The server responds with structured data, usually JSON, which you'll learn to work with throughout this book.

The next page goes deeper into those HTTP methods, statelessness, JSON, and status codes, the four mechanics that make REST work.