Understanding APIs: A Practical Guide for New Developers

An API is just an agreed-upon way for two pieces of software to talk to each other — most confusion about them comes from skipping that simple definition and jumping straight to the jargon.

Requests and responses, at the core

When your app calls an API, it sends a request — a method (GET to read data, POST to create it, PUT/PATCH to update it, DELETE to remove it), a URL, and sometimes a body of data. The server processes that request and sends back a response, usually including a status code and some data, typically formatted as JSON.

fetch("https://api.example.com/users/42")
  .then(res => res.json())
  .then(data => console.log(data));

Status codes tell you what actually happened

A response in the 200 range means success. 400-range codes mean your request had a problem (404 = not found, 401 = you're not authenticated, 400 = malformed request). 500-range codes mean the server itself failed. Reading the status code first, before even looking at the response body, will save you a lot of confused debugging.

Authentication: proving who you are

Most real APIs require some form of credential — an API key, a token, or a full login flow — sent along with each request, usually in a header. Never hard-code these credentials directly into client-side code you ship to users; anyone can open their browser's network tab and read them.

Rate limits exist for a reason

Most APIs cap how many requests you can make in a given window, to protect their own infrastructure. Hitting a rate limit isn't a bug in your code — it's the API doing its job. Build in reasonable delays or caching rather than hammering an endpoint in a tight loop.

REST is a convention, not a law

"RESTful" APIs follow a loose convention: resources are nouns (/users, /orders), and HTTP methods are the verbs acting on them. It's not enforced by any technology — it's a widely agreed style that makes APIs predictable to use once you know the pattern.

The takeaway

Requests, responses, status codes, and authentication cover the vast majority of what you need to work with any real-world API. Everything else — GraphQL, webhooks, pagination strategies — is a variation on this same underlying idea.