Web APIs and HTTP
Much of modern software is built by connecting to web APIs: services that other programs call over HTTP to get weather, maps, payments, or AI responses.
What an API is
An application programming interface (API) is a defined way for programs to interact. A web API exposes operations over HTTP: a client sends a request to a URL, called an endpoint, and receives a response, usually JSON. Weather services, payment processors, mapping tools, and social networks all offer web APIs.
REST conventions
REST (representational state transfer), described by Roy Fielding in 2000, is the most common API style. Resources have URLs, such as /books/42, and HTTP methods express actions: GET reads, POST creates, PUT or PATCH updates, and DELETE removes. Requests are stateless: each contains everything the server needs to handle it.
Requests and responses
A request has a method, URL, headers (metadata such as Content-Type: application/json), and sometimes a body. Query parameters filter or page results: /books?author=austen&page=2. A response has a status code, headers, and a body. 2xx codes mean success (200 OK, 201 Created), 4xx mean client errors (400 Bad Request, 401 Unauthorized, 404 Not Found, 429 Too Many Requests), and 5xx mean server errors.
Calling an API from code
In Python, the requests library makes HTTP simple: r = requests.get(url, params={"q": "london"}, timeout=10); r.raise_for_status(); data = r.json(). In JavaScript, fetch(url).then(res => res.json()) does the same. Always set timeouts, check status codes, and handle network failures gracefully.
Authentication and keys
Most APIs require authentication, often an API key or token sent in a header, such as Authorization: Bearer followed by the token. Keys are secrets: never hard-code them into source files or commit them to repositories. Store them in environment variables or a secrets manager, and revoke any key that is accidentally exposed.
Rate limits and pagination
Providers limit how many requests a client can make per period; exceeding the limit returns 429. Clients should respect limits, cache results, and retry with exponential backoff, waiting longer after each failure. Large result sets are split into pages; the client follows page numbers or cursor tokens until no more results remain.
Other API styles
GraphQL, released publicly by Facebook in 2015, lets clients request exactly the fields they need in one query. gRPC uses compact binary messages for fast service-to-service calls. Webhooks reverse the direction: the provider calls your URL when an event happens, such as a completed payment, instead of you repeatedly asking.
Worked example
Fetching a user's public repositories from a code-hosting API: r = requests.get("https://api.example.com/users/ana/repos", params={"per_page": 50, "page": 1}, timeout=10). If r.status_code is 200, repos = r.json() gives a list of dictionaries; names = [x["name"] for x in repos]. If it is 404, the user does not exist; if 429, wait and retry; and if 50 items came back, request page 2.
Key takeaways
Web APIs let programs exchange data over HTTP, usually as JSON, via endpoints. REST maps resources to URLs and actions to GET, POST, PUT or PATCH, and DELETE, with stateless requests. Status codes signal success (2xx), client errors (4xx), and server errors (5xx). Use libraries such as requests or fetch, with timeouts and error handling. Keep API keys out of code, in environment variables or secret stores. Respect rate limits with backoff, and follow pagination. GraphQL, gRPC, and webhooks are alternatives.
Flashcard
Application programming interface
Check your understanding
An API call returns status 429. What should a well-behaved client do?