What Is an API?

APIs are the plumbing of modern software. Every app you use — Slack, Spotify, Uber — is a pile of APIs talking to other APIs. Understanding them is maybe the single most important concept after learning to program.

This guide explains APIs in plain English, with enough detail to actually use them. No hand-waving.

1. API = “Application Programming Interface”

A contract that lets one program talk to another. You send a request, you get a response. The classic analogy: a restaurant menu. You don’t tell the kitchen how to cook — you order by name, they deliver.

2. What a web API looks like

A URL like https://api.example.com/users/42. You send an HTTP request, you get back JSON (usually). That’s 95% of what “API” means in a modern web context.

3. HTTP methods in one breath

GET to read. POST to create. PUT/PATCH to update. DELETE to delete. That’s the entire REST alphabet. Different verbs, same URL structure — the verb tells the server what you want.

4. Status codes matter

2xx = success. 3xx = redirect. 4xx = you messed up (400 bad request, 401 auth missing, 404 not found). 5xx = they messed up (500 server error). Reading codes quickly is a debugging skill.

5. JSON is the lingua franca

Most APIs send and receive JSON: {"name": "Ada", "age": 30}. Keys are strings, values are strings/numbers/booleans/arrays/objects. Every language has built-in JSON support. See JSON to CSV converter for quick conversions.

6. Authentication: API keys and tokens

Most APIs require an API key (a secret string) sent in a header like Authorization: Bearer xyz123. Never commit keys to git. Use env vars. This is the single most common security screw-up in startups.

7. REST vs GraphQL vs RPC

REST uses URLs + HTTP verbs. GraphQL exposes a single endpoint you query flexibly. RPC (gRPC) is function calls across the wire. REST is the default; the others are specialized. See REST vs GraphQL.

8. How to test an API

Use curl, Postman, or Insomnia. Hit the endpoint, inspect the response. The docs lie sometimes — the real contract is what the server actually returns. Test before you build against it.

9. Rate limits and pagination

Most APIs cap how many requests per minute you can make and page large result sets. Respect the limits, handle 429 responses, follow pagination links. Hitting rate limits in prod is a rookie mistake.

10. Webhooks = APIs in reverse

Normally you call them. With webhooks, they call you when something happens (new order, message, etc.). You give them a URL, they POST to it. Great for event-driven flows.

11. Documentation is everything

Good API docs make or break adoption. Stripe is the gold standard. When building your own API, the docs are as important as the code. Bad docs mean users give up.

12. Building your own

Pick a language/framework (Express, FastAPI, Go net/http). Define routes. Return JSON. Add auth. Deploy. You’ve built an API. The concept is simpler than the jargon implies. See frontend vs backend for context.