What is an API? A plain-language guide to how APIs work

An API (application programming interface) is a way for one program to talk to another — a contract that says: "send me a request in this shape, and I'll answer in that shape." It is a connection between computers or between computer programs, offering a service to other pieces of software. When a weather app shows today's forecast, it is almost always reading an API.

What an API actually is

An API is a software interface: a documented set of rules that describes how to build a connection between programs. A system that follows those rules is said to "expose" an API. The term can refer either to the specification (the document that describes the interface) or to the implementation (the running service).

The point of an API is that you never need to know what happens inside. The service keeps its internal logic private and publishes only the "doors" other programs can knock on. That separation is why a company can change its internals without breaking every app that depends on it.

How an API call works over HTTP

Most web APIs today are HTTP APIs, and HTTP is a client-server protocol: one entity — the user-agent, often a browser but sometimes another program — sends a request, and the server answers. A request has three parts:

• A URL that identifies what you want (for example, https://api.example.com/v1/users)
• A method that says what you want to do with it
• Headers that carry extra information, like an API key or a content type

The server replies with a response: a status code that says whether it worked, and usually a body containing the data.

The HTTP methods you'll actually meet

A quick note on "idempotent": it means calling the same request once or several times gives the same result, with no extra side effects. PUT and DELETE are idempotent; POST is not — which is why accidentally submitting the same order twice can create the order twice.

Reading an API response

The status code tells you most of the story:

• 200 OK — the request succeeded; for GET, the resource is in the response
• 201 Created — a new resource was created, typically after a POST request
• 204 No Content — success, but there is nothing to send back
• 400 Bad Request — the server can't process the request; something is wrong with what you sent
• 401 Unauthorized — semantically "unauthenticated": you didn't prove who you are (missing or invalid API key)
• 404 Not Found — the resource doesn't exist
• 429 Too Many Requests — you hit a rate limit
• 500 Internal Server Error — the server failed on its side

The body is usually JSON these days. A typical response might look like:

{ "id": 42, "name": "Debod", "plan": "free" }

REST: the style behind most web APIs

REST is a software architectural style that was created to describe and guide the architecture of the World Wide Web. It emphasizes uniform interfaces, independent deployment of components, scalability of interactions, and a layered architecture that promotes caching. Most public APIs call themselves "REST APIs" even when they follow the style loosely. The practical takeaway: resources identified by URLs, manipulated with HTTP methods, and exchanged as JSON.

Why APIs matter

• Integration: apps don't need to reinvent payments, maps, or login — they call someone else's API.
• Automation: scripts and tools can act on your behalf through APIs — deploying, sending messages, pulling reports.
• Separation of concerns: frontend and backend can evolve independently as long as the contract holds.

API keys and safety

Most APIs use an API key — a secret string that identifies you — sent in a request header. Treat keys like passwords: never put them in client-side code or public repositories. The server uses them to authenticate you and to apply rate limits; the 401 and 429 codes above are exactly what you see when authentication fails or you exceed a limit.

FAQ

What is the difference between an API and a web service?

The terms overlap, but they are not the same. An API is any documented contract that lets one program call another. A web service is a specific kind of API — one that talks over the network, usually using HTTP. So every web service is an API, but not every API is a web service: an operating system also exposes APIs (system calls), and a library exposes APIs (its public functions) without any HTTP involved.

Are GET, POST, PUT, PATCH, and DELETE always supported?

Not always. The standard says what each method means, but a specific API is free to only implement the methods it actually needs. The most common public pattern is to expose GET (read) and POST (create or trigger an action), and to overload POST for updates instead of offering PUT or PATCH. The verbs are a style, not a rule.

What does it mean when an API is "RESTful"?

A RESTful API is one that follows the REST architectural style: resources are identified by URLs, manipulated with standard HTTP methods, and exchanged in a stateless way. In practice, very few public APIs are 100% REST — most call themselves "REST" loosely. The practical signal: the same data can usually be reached with a URL like /users/42 and modified with GET, POST, PUT/PATCH, or DELETE.

Why do I get a 401 instead of a 403 when my API key is wrong?

A 401 means "you have not proved who you are" — the server does not know your identity, usually because the API key is missing or invalid. A 403 means "I know who you are, but you are not allowed to do this." With a wrong key, the server cannot identify you at all, so it answers 401. Once the key is valid but lacks permission for that resource, the same server would answer 403.