The one idea
An API is one program asking another program for something, in a format the first one can use.
That last clause is what makes it different from a website. A website sends pages formatted for human eyes. An API sends structured data formatted for a program. Same information, different packaging, for a different reader.
A menu of things one app is willing to do for another app, and the exact words you have to use to ask.
A documented set of addresses you can send requests to. Each says what it needs, what it returns, who is allowed, and how often.
An interface contract, most commonly HTTP endpoints exchanging JSON, with authentication, versioning and rate limits as part of the contract.
Request and response
Every API interaction is two messages.
The request says: what do I want, from where, as whom, with what details. The response says: did it work, and here is the result.
| Part of a request | What it is |
|---|---|
| Method | What kind of thing you want. GET = give me. POST = create this. PUT/PATCH = change this. DELETE = remove this. |
| Address | Which thing, e.g. /api/bookings/482 |
| Headers | Information about the request, including who you are |
| Body | The actual data, for creating or changing |
The response comes back with a status code — a three-digit number that says what happened. You only need the shape of them:
| Code | Means | Typical cause |
|---|---|---|
| 200s | It worked | — |
| 400s | You made a mistake | Bad data, missing field, wrong permissions, not found |
| 429 | You asked too often | Rate limit |
| 500s | They made a mistake | Their server failed |
That 400 versus 500 split is genuinely useful. A 400 means stop and fix your request. A 500 means try again later, because there is nothing on your side to fix.
JSON, in one minute
JSON is the format most APIs use. It is text, and it is readable once you know the two shapes it is built from.
{
"booking_id": 482,
"name": "Priya Sharma",
"confirmed": true,
"slots": ["10:00", "10:30"],
"clinic": {
"name": "Green Park Clinic",
"city": "Delhi"
}
}
{ }holds labelled values. Read as "this thing has these properties".[ ]holds a list. Read as "these, in order".- Text is in quotes. Numbers and
true/falseare not. - Things nest —
clinicis an object inside an object.
That is the whole format. When you see a wall of JSON, find the outermost bracket and read the labels. You do not need to understand every field; you need to find the two you came for.
Try this
Using the JSON above: what is the city, how many slots are booked, and is this booking confirmed?
Authentication, and why keys are dangerous
Most APIs need to know who is asking. The common method is an API key — a long string you send with every request that identifies your account.
Treat a key as a password, because it is one. Anything the key can do, anyone holding it can do, billed to you and attributed to you.
Rate limits
A rate limit is a cap on how many requests you may make in a period — "1,000 per hour", "10 per second". Exceed it and you get 429 responses.
Limits exist because every request costs the provider something. They are not an obstacle to route around; deliberately evading one usually breaches the terms of service.
What they mean practically: an automation that processes 5,000 records cannot fire 5,000 requests as fast as it can. It has to pace itself, and when it gets a 429 it should wait and retry rather than hammering. Well-built integrations slow down when told to. Badly built ones get blocked.
Webhooks: the reverse direction
With an API, you ask. With a webhook, you are told.
You give the other system an address of yours. When something happens, it sends
a request to that address immediately. This is the event trigger from
trigger-action-condition.
| API call (polling) | Webhook | |
|---|---|---|
| Direction | You ask them | They tell you |
| Timing | When you check | Within seconds of the event |
| Cost | Every check, even when nothing changed | Only when something happens |
| Needs | Their permission and a key | An address of yours that is publicly reachable |
| Fails by | Missing changes between checks | Missing the message if you were down |
Webhooks are more efficient and more immediate. The catch is that you must have somewhere public for the message to arrive, and you must handle the same event arriving twice — senders retry when they are unsure you received it.
Your CRM sends a webhook when a deal is marked won. Your automation receives it and posts to the sales channel, instantly.
The polling alternative — checking the CRM every fifteen minutes — means up to fifteen minutes of delay and 96 pointless checks a day on the days nothing closes.
Asked in an interview how you would connect two systems, "check if either has an API, look at what endpoints exist, check the rate limits and whether it needs a paid plan" is a better answer than naming a tool.
It shows you know that the integration's feasibility is decided by the documentation, not by the tool you would use.
Reading API documentation without writing code
1 of 6Find the endpoint list.
Look for a page titled Reference, Endpoints, or Resources. It lists what the API can do. If you cannot find one, that is itself an answer about how usable this API will be.
Your challenge
Level 3 · IndependentPick a tool you use that has public documentation. Without writing a line of code, answer six questions in writing:
- What can you read through the API?
- What can you create or change?
- What credential does it need, and how do you get one?
- What is the rate limit?
- Does it support webhooks, and for what events?
- Name one thing you assumed you could do that you cannot.
Question 6 is the point. Every API has a limitation that only appears when you read carefully, and finding it before you build is the entire skill.
What people usually get wrong
- Assuming "has an API" means it does what you need. Read the endpoints. Read-only APIs are extremely common.
- Putting the key in the frontend or the repository. The two most common ways credentials leak.
- Ignoring rate limits until blocked. Then your account is suspended at the worst moment.
- Not handling failure. Networks fail. Servers restart. An integration without retry logic is an integration that silently loses records.
- Retrying instantly and forever. Retrying a 400 is pointless — you sent something wrong. Retrying a 500 without waiting makes their outage worse.
- Assuming a webhook arrives exactly once. Senders retry. Design so a repeated message is harmless.
How someone experienced does it
Experienced integrators read the errors section of documentation first, not the endpoints. What can go wrong, and what the API does about it, tells you more about how much work this integration will be than the happy path ever does.
They also assume the API will change. Versioning exists because providers deprecate things. Anyone building a business process on a third-party API should know how that provider announces breaking changes and should be subscribed to it — otherwise you find out from a failure.
And they check whether the data they need is actually in the response before building anything. "We can get the orders" often means orders without line items, requiring a second call per order, which multiplies your request count and collides with the rate limit. That discovery belongs at the reading stage, not the debugging stage.
Why the same API can be free and expensive at once
API pricing usually charges for requests, not for the data. So the way you ask determines the cost more than what you ask for.
Fetching 1,000 records one at a time is 1,000 requests. Fetching them in pages of 100 is 10. Same data, two orders of magnitude apart in cost and in time.
This is why documentation talks about pagination, bulk endpoints and filtering. They are not conveniences; they are how you stay inside a limit. An integration that works fine in testing with 20 records and collapses in production with 20,000 has usually made this exact mistake.
The corresponding habit: before building, estimate your request count at real volume, then compare it to the limit. If the numbers are close, redesign now.
Prove it
Read the documentation for one API and write a one-page assessment: what you can do, what you cannot, what credential you need, what the limits are, and whether the integration you had in mind is actually possible.
Ending with "it is not possible for this reason" is a complete and valuable result. Knowing that in an hour of reading instead of a week of building is what this skill buys you.
Keep learning this
Paste this into any AI assistant. It turns the assistant into a tutor that tests you instead of just answering you.
Act as an experienced practitioner who is good at teaching. I have just learned what APIs are and how to read API documentation. Assume I am intelligent but relatively new to this — treat me as intermediate level. Work through this in order, and wait for my reply at each step: 1. Ask me 5 questions that test whether I actually understood what APIs are and how to read API documentation. Do not reveal the answers yet. 2. After I answer, tell me which parts I got right, which I got wrong, and which I only half-understand. Explain only what I misunderstood — do not re-teach what I already know. 3. Give me one practical challenge based on something I could genuinely encounter at work or in daily life. Do not solve it for me. 4. Evaluate my solution the way an experienced person would judge it, including what a professional would have done differently. 5. Tell me what to learn next, and why that comes next. 6. Give me trustworthy sources for deeper study — prefer official documentation, primary research or standards bodies over blogs and videos. Rules for you: no buzzwords. No motivational filler. Say "I'm not certain" when you are not certain, and tell me which parts of your answer I should verify myself. Clearly separate facts from your recommendations and your opinions.
Become independent at this
Use this when you want a path from where you are to actually good, with checkpoints you can test yourself against.
I want to become independently capable at understanding and evaluating APIs — not permanently dependent on AI, tutorials or step-by-step guides. Design a progression for me with five stages: Beginner, Guided practice, Independent practice, Real-world application, Professional level. For each stage tell me: - what I must know - what I must be able to do without help - the mistakes people make at this stage - one practical challenge - one real project that would prove I reached this stage - one way I can test myself honestly Then tell me the signals that I am ready to move to the next stage, and the signals that I have skipped ahead too early. Keep the theory to the minimum I actually need. Focus on ability I can transfer to situations you and I have not discussed.