What Is an API? A Visual Guide

An API (application programming interface) is a set of rules that lets one piece of software ask another piece of software for data or to do something, without knowing how it works inside.

When a weather app shows tomorrow's forecast, it did not measure the weather. It asked a weather service through that service's API, and the service answered with the forecast as data. The app only needed to know how to ask.

That is the whole idea. The rest of this note is the detail: what a request looks like, what an endpoint and an API key are, and how REST fits in. The diagram below is live, and one of the requests is real.

Watch one API call

Pick a request. Watch it leave your app, get checked by the API, reach the server, and come back with an answer.

The first button makes a real request to a tiny API running on this website. The others are simulated so you can see the cases that are hard to trigger on purpose, like a missing key.

The restaurant version

The classic analogy holds up well:

The menu is the API's documentation. It lists what you can ask for and how.
The waiter is the API. You never walk into the kitchen; you tell the waiter, and the waiter brings back what you ordered.
The kitchen is the server: the database and code that actually do the work.

You can order without knowing the recipe, and the kitchen can change its ovens without reprinting the menu. That separation is why APIs exist: two systems agree on how to talk, and each is free to change everything else.

How an API call works, step by step

Most APIs you will meet are web APIs that talk over HTTP, the same protocol your browser uses to load pages. A single call has five parts:

The client builds a request. It picks a method (what to do), an endpoint (where), headers (extra information, like a key), and sometimes a body (data to send).
The request travels over the internet to the API's address.
The API checks it. Is there a valid key? Is the caller allowed to do this? Is the request well formed? If not, it answers with an error straight away and the server is never involved.
The server does the work. It reads from or writes to a database, runs code, or calls other services.
The API sends back a response. It contains a status code (did it work?) and usually a body of data, most often in JSON.

Here is what that looks like as plain text. A request:

GET /v1/weather?city=tokyo HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_4f2a…
Accept: application/json

And its response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "city": "Tokyo", "temp_c": 18, "conditions": "clear" }

What is an API call?

An API call (or API request) is one round trip: the client sends one request and gets one response. "Our app makes three API calls when it loads" means it asks three questions and waits for three answers.

API calls are also how many services measure usage and bill for it. When a provider says "first 10,000 calls free", it is counting these round trips.

What is an API endpoint?

An endpoint is one specific address an API listens on, combined with the method used to reach it. Each endpoint does one job:

Method + endpoint	What it does
`GET /v1/notes`	List all notes
`GET /v1/notes/42`	Get note 42
`POST /v1/notes`	Create a note
`PATCH /v1/notes/42`	Change part of note 42
`DELETE /v1/notes/42`	Delete note 42

The same URL can be several endpoints: GET /v1/notes/42 reads a note, while DELETE /v1/notes/42 removes it. The method is part of what makes an endpoint an endpoint.

The methods

Method	Means	Changes data?
`GET`	Read something	No
`POST`	Create something new	Yes
`PUT`	Replace something entirely	Yes
`PATCH`	Change part of something	Yes
`DELETE`	Remove something	Yes

The status codes you will see most

Code	Meaning
`200 OK`	It worked; here is your data
`201 Created`	It worked; something new was made
`204 No Content`	It worked; nothing to send back
`400 Bad Request`	Your request is malformed
`401 Unauthorized`	Missing or invalid credentials (often the API key)
`403 Forbidden`	We know who you are, but you are not allowed
`404 Not Found`	That endpoint or item does not exist
`429 Too Many Requests`	Slow down; you hit the rate limit
`500 Internal Server Error`	The server broke; not your fault

A quick rule: 2xx means success, 4xx means the client did something wrong, 5xx means the server did.

What is an API key?

An API key is a long secret string that identifies which app is calling. The API uses it to:

Allow or refuse the request (the "No API key" button in the diagram gets a 401).
Count usage for rate limits and billing.
Turn off one app without affecting anyone else, by revoking its key.

Keys are usually sent in a header, such as Authorization: Bearer … or X-API-Key: ….

Two things trip people up:

Treat a key like a password. Anyone who has it can make calls as you, and you pay for them. Keep keys on your server, in environment variables, and never commit them to Git or ship them inside a website's JavaScript, where anyone can read them.
An API key identifies an app, not a person. When an app needs to act on behalf of a specific user ("Sign in with Google"), APIs use a different system, usually OAuth, which hands out short-lived tokens per user.

API vs REST API

API is the general idea: any defined way for software to talk to other software. REST is one particular style of designing web APIs, described by Roy Fielding in 2000. A REST API:

treats data as resources with their own URLs (/notes/42),
uses standard HTTP methods for actions (GET, POST, DELETE…),
is stateless: every request carries everything needed to answer it,
usually returns JSON.

So every REST API is an API, but not every API is a REST API. Other common styles:

GraphQL: one endpoint, and the client describes exactly which fields it wants back.
gRPC: compact binary messages, popular for communication between services inside a company.
WebSockets: a connection that stays open so the server can push updates without being asked.
Non-web APIs: your browser exposes APIs to JavaScript (the soundtrack on this site is generated with the Web Audio API, and its blob animations run on requestAnimationFrame), and operating systems and code libraries expose APIs too.

API examples you already use

Payments: a shop sends your card details to a payment provider's API and gets back "approved" or "declined".
Maps: a delivery app embeds a map by calling a maps API with an address.
Weather: forecast apps ask a weather API for the data.
Sign in with Google or Apple: the site asks Google's or Apple's API to confirm who you are.
Browser APIs: when a site asks for your location, it uses the browser's Geolocation API.

Try a real API now

This site runs a tiny public API for this note. Paste this into your browser's console (or a terminal) and you have made an API call:

const response = await fetch("https://blimoro.tech/api/ping");
const data = await response.json();
console.log(response.status, data);

curl https://blimoro.tech/api/ping

It answers with JSON:

{
  "message": "Hello from the Blimoro API",
  "time": "2026-10-17T21:43:31.973Z",
  "you_asked_for": { "method": "GET", "path": "/api/ping" }
}

FAQ

What does API stand for?

Application programming interface. "Interface" is the key word: it is the surface where two programs meet, like the buttons on a microwave are the interface to the electronics inside.

Is an API a server?

No. The server is the computer and software doing the work. The API is the agreed way of talking to it: the endpoints, methods, and data formats. One server can offer several APIs, and one API can be spread across many servers.

What is the difference between an API and an SDK?

An API is the set of rules for talking to a service. An SDK (software development kit) is ready-made code, in a specific programming language, that calls the API for you so you do not have to write the HTTP requests by hand.

Are APIs free?

Some are, many are not. Most commercial APIs offer a free tier and then charge per call or per month, which is one reason API keys exist: they tie every call to an account.

Is JSON an API?

No. JSON is a data format, a way of writing data as text. Many APIs use JSON for their requests and responses, but the API is the set of rules, and JSON is just the language the data is written in.