HTTP fundamentals

Before you can write a script that talks to an API, you need to understand the language it speaks. Every API call you make — whether you are fetching weather data, posting a message, or querying a database over the network — is an HTTP request. The server replies with an HTTP response. That exchange is the whole conversation.

The request/response cycle

HTTP is a request/response protocol. A client (your script) initiates every exchange by sending a request. The server processes it and sends back exactly one response. Neither side can push unsolicited messages mid-exchange — the client always goes first.

A request has four parts:

1. Method — what action you want to perform (see below).
2. URL — the address of the resource, e.g. https://api.example.com/users/42.
3. Headers — key/value metadata attached to the request.
4. Body — optional payload, used for POST and PUT requests.

A response has three parts:

1. Status code — a three-digit number indicating success or failure.
2. Headers — key/value metadata from the server.
3. Body — the returned data, usually JSON or plain text.

Methods

HTTP methods describe what you want to do with a resource. The four you will use most often:

APIs do not always follow these conventions perfectly, but they are the standard expectation. A GET /users endpoint should never delete anything; a DELETE endpoint should never return data you did not have before.

Status codes

Status codes are grouped by their first digit:

• 2xx — Success. 200 OK is the standard success response. 201 Created means a new resource was created (typical after a POST). 204 No Content means success but there is nothing to return.
• 3xx — Redirection. The resource has moved. Your HTTP client usually follows these automatically.
• 4xx — Client error. Something in your request was wrong. Common ones: 400 Bad Request (malformed payload), 401 Unauthorized (missing or invalid credentials), 403 Forbidden (authenticated but not allowed), 404 Not Found (resource does not exist), 429 Too Many Requests (you are being rate-limited).
• 5xx — Server error. The server failed. 500 Internal Server Error means something went wrong on the server side — not your fault, but you need to handle it gracefully.

Headers

Headers carry metadata that neither party wants to embed in the URL or body. A few you will encounter constantly:

• Content-Type — tells the receiver what format the body is in. application/json is the default for most APIs.
• Authorization — carries credentials. Usually looks like Authorization: Bearer <token>.
• Accept — tells the server what format you want back.
• X-RateLimit-Remaining — a common custom header that tells you how many requests you have left in the current window.

Headers are case-insensitive in HTTP/1.1, but by convention they are written in Title-Case.

Where to go next

Next: making requests — translating this model into Python with the requests library: sending a GET, reading the response body, and handling non-200 status codes.