How a Request Actually Works
Every API interaction follows the same pattern: a client sends a request to a server, the server processes it, and returns a response. The details of what happens in between depend on the API's design.
The Client Makes a Request
When you open a weather app, the app sends an HTTP request to a URL like https://api.weather.com/v1/forecast?city=London. This URL is called an endpoint. The path (/v1/forecast) tells the server which data you want, and the query parameter (city=London) provides specifics.
The request also includes an HTTP method (usually GET for retrieving data), headers with metadata like content type and authentication, and sometimes a body with additional data.
The Server Processes It
The receiving server parses the request, checks if the client has permission, validates the input, queries the database or runs the necessary logic, and constructs a response. If anything goes wrong bad input, missing permissions, server error it returns an error code instead of data.
This processing typically takes 50-500 milliseconds for well-designed APIs. If it takes longer, the API is either doing heavy computation or something is poorly optimized.
The Response Arrives
The server sends back an HTTP status code (200 for success, 404 for not found, 500 for server error) along with the data. For web APIs, this data is almost always JSON a lightweight format that organizes information as key-value pairs.
Why not just scrape the website? You could parse HTML from a web page, but HTML is designed for visual layout it changes when the site redesigns, includes navigation and ads you don't need, and is harder to parse reliably. APIs give you exactly the data you need, in a consistent format, without the extra noise.
What Comes Back: Responses and JSON
JSON (JavaScript Object Notation) became the default format for web APIs because it's readable by humans, parseable by every programming language, and lighter than XML the format it largely replaced.
What JSON Looks Like
A weather API might return something like this: {"city": "London", "temp_c": 18, "condition": "Partly Cloudy", "humidity": 65}. Each piece of data has a key (like "temp_c") and a value (like 18). Your app reads the keys it needs and ignores the rest.
Real API responses are usually more complex nested objects, arrays of items, pagination metadata. But the structure is always the same: keys and values, organized hierarchically.
Status Codes Tell You What Happened
Every API response includes an HTTP status code. The ones you'll see most often: 200 (success), 201 (created something new was saved), 400 (bad request you sent invalid data), 401 (unauthorized missing or wrong credentials), 404 (not found the endpoint or resource doesn't exist), and 500 (server error something broke on their end).
Well-designed APIs also return error details in the response body, not just the status code. A 400 error might include a message like {"error": "city is required"} so you know exactly what to fix.
Common mistake: Writing code that only handles the success case. In production, APIs fail regularly rate limits get hit, servers go down, network requests time out. Always handle error responses and implement timeouts (usually 5-10 seconds for a single request). Code that assumes a 200 response will eventually break.
HTTP Methods: The Vocabulary of APIs
When you send a request, you specify an HTTP method that tells the server what you want to do. Most web APIs rely on four methods.
| Method | Purpose | Example |
|---|---|---|
| GET | Read data | GET /users/42 — fetch user #42's profile |
| POST | Create something new | POST /users — create a new user |
| PUT | Replace existing data | PUT /users/42 — update all of user #42's info |
| DELETE | Remove data | DELETE /users/42 — delete user #42 |
There's also PATCH, which updates part of a resource (unlike PUT, which replaces the whole thing). Most modern APIs use PATCH for updates because sending the entire object just to change one field is wasteful.
Authentication: Proving You Belong
Most APIs aren't public. They require some form of authentication to verify that the calling application has permission to access the data.
API Keys
The simplest form. You sign up, get a unique string (like sk_live_abc123...), and include it in every request, usually in the header. The server checks the key against its database. If it's valid, the request proceeds.
API keys are easy to implement but have limitations they can't easily distinguish between different users of your app, they're hard to revoke without breaking all requests, and if they leak (committed to GitHub, for example), anyone can use them.
OAuth 2.0 and Bearer Tokens
More sophisticated. The user logs in through a provider (like "Sign in with Google"), and your app receives a temporary token. That token goes in the request header as Authorization: Bearer <token>. Tokens expire after a set time, limiting the damage if one is stolen.
Most serious APIs use OAuth. If you've ever connected an app to your Google account or Slack workspace, you've gone through an OAuth flow. The API never sees your password it just gets a token that says "this user granted this app permission to read their data."
Never put API keys in frontend code. Anything in your JavaScript, HTML, or mobile app binary can be extracted by anyone. API keys that appear in client-side code should be restricted to non-sensitive operations (like public read access). For anything that costs money or accesses private data, authenticate through a backend server that holds the credentials securely.
Real APIs You Use Every Day
APIs aren't abstract they're running constantly behind the scenes of practically every app you interact with.
Payment Processing
When you buy something online, the checkout page sends your card details (through a secure token, not raw numbers) to the Stripe or PayPal API. The API validates the card, processes the charge, and returns a success or failure response. The e-commerce site never directly handles the payment logic it just sends a request and reacts to the response.
Maps and Location
Google Maps, ride-hailing apps, and food delivery apps all use mapping APIs. When Uber shows you nearby drivers, your app sends your GPS coordinates to Uber's API, which returns a list of drivers with their locations, names, and ratings. The app then plots them on a map. Without the API, the app would have no way to know where drivers are.
Social Media Integrations
When you see a Twitter feed embedded in a news article, that's Twitter's API at work. The news site requests the tweet data, and Twitter returns the text, images, like count, and metadata. The news site formats it however it wants. If Twitter changes its design, the embedded tweet still works because the API response format stays consistent.
No-Code Tools
Tools like Zapier, Make, and n8n are essentially API orchestration platforms. When you set up a rule like "when a new row is added to Google Sheets, send a Slack message," Zapier is calling the Google Sheets API to detect changes and the Slack API to post the message. You never see the requests, but that's what's happening underneath.
Types of APIs Beyond REST
REST is the most common style you'll encounter, but it's not the only option. Understanding the alternatives helps when you encounter them in documentation or job requirements.
REST APIs
Uses standard HTTP methods and URLs. Each URL represents a resource (like /users/42). Stateless each request contains everything the server needs. Simple, widely supported, and works well for most web and mobile applications. This is what 80%+ of public web APIs use.
GraphQL
Created by Meta. Instead of multiple endpoints for different data, you send a single query that specifies exactly which fields you want. One request can fetch a user, their posts, and their followers instead of making three separate API calls. Used by GitHub, Shopify, and many modern platforms. The trade-off: more complex to set up on the server side, and caching is harder than with REST.
WebSocket APIs
Regular APIs follow a request-response pattern: you ask, they answer. WebSockets keep a persistent connection open, allowing the server to push data to the client without being asked. Used for chat applications, live sports scores, stock tickers, and multiplayer games anything that needs real-time updates.
Webhook APIs
Reverse direction instead of you calling the API, the API calls you. You give a service a URL, and when something happens (a payment succeeds, a form is submitted), they send an HTTP request to your URL with the event data. Used by Stripe, GitHub, and Slack for event notifications.
Learning path: If you're just starting, learn REST first. It teaches you the fundamentals HTTP methods, status codes, JSON, authentication that apply to all other types. Move to GraphQL or WebSockets once you're comfortable with REST and have a specific use case that justifies them.
