A menu, not a kitchen
An API is a published list of things a program will do for you, and the exact way to ask. The restaurant version is worn out but accurate: the menu tells you what you can order and how to order it, and you never see the kitchen. You also can't order something that isn't on the menu, which is the part people forget.
The point is separation. The service can rewrite its entire internals tomorrow, and as long as the requests and responses stay the same, everything built on it keeps working.
Anatomy of a request
curl https://api.example.com/v1/customers/42 \ -H "Authorization: Bearer sk_live_xxx" \ -H "Accept: application/json"- The method — GET here, implied by curl's default. It says what kind of action you want
- The URL — which service, which version, which resource, which one
- Headers — who you are (Authorization) and what you can accept
- A body — not present on a GET; on a POST it carries the data you're sending
{ "id": 42, "name": "Aarav Sharma", "email": "aarav@example.com", "created_at": "2026-03-14T09:20:00Z", "plan": "pro"}The response arrives with a status code and, usually, JSON — a text format of keys and values that every language can read. That's most of what an API is: text out, text back.
Methods and status codes
| Method | Means | Changes data? |
|---|---|---|
| GET | Give me this | No |
| POST | Create this | Yes |
| PUT / PATCH | Replace / update this | Yes |
| DELETE | Remove this | Yes |
| Range | Meaning | Example |
|---|---|---|
| 2xx | It worked | 200 OK, 201 Created |
| 3xx | It moved | 301 Moved Permanently |
| 4xx | Your request was wrong | 401 unauthenticated, 403 forbidden, 404 not found, 429 too many requests |
| 5xx | Their server broke | 500 Internal Server Error, 503 unavailable |
Keys, limits, and versions
An API key identifies your application. Treat it exactly like a password: it goes in an environment variable on your server, never in frontend code, never in a repository. A key committed to a public repository is typically found and used within minutes.
Rate limits cap how many requests you can make in a window. Hitting one returns 429, and the correct response is to wait and retry with increasing delays — not to retry immediately in a loop, which is how a temporary limit becomes a permanent ban.
The `/v1/` in the URL is a version. It exists so the provider can ship a breaking change as `/v2/` without breaking you. When you see it, pin to it deliberately rather than assuming the latest.
Reading any API's documentation
- Find the authentication page firstEverything else fails without it, and it's usually three lines.
- Find one endpoint that only readsMake that request before writing any code. curl or an HTTP client is enough.
- Read the error sectionIt tells you the rate limit and the failure shapes you'll be handling for the rest of the integration.
- Then write the smallest script that calls itPrint the raw response before parsing it. Most integration bugs are visible in that first print.
Common mistakes
- Putting an API key in frontend code, where anyone can read it
- Retrying immediately on 429 instead of backing off
- Assuming a 200 means success — some APIs return errors inside a 200 body
- Building against the newest version without pinning, then being broken by someone else's release
- Not handling the case where the service is simply down
Key takeaways
- An API is a published list of requests a service accepts, and their responses
- Method plus URL plus headers plus body — that's a request, in every language
- The first digit of the status code tells you whose problem it is
- Keys are passwords; they belong on your server and nowhere else
Try it yourself
Pick any public API that needs no key and make one GET request with curl or your browser. Read the raw JSON before writing a line of code around it. The habit of looking at the real response first prevents most integration bugs.