What an API is

What you will learn What an API actually is, what endpoint, key and SDK each refer to, and why you would call one when a perfectly good screen exists.

A counter for people, a counter for programs

A bank has two. The one people queue at, and the dedicated line other banks' systems connect to. An API is the second one.

	Screen (UI)	API
Used by	people	other programs
Shape	buttons and tables	addresses and JSON
Good at	looking and judging	repetition, volume, automation

API (Application Programming Interface) — literally "the surface built for programs to use". There is nothing more to it.

Endpoints — the individual counters

An API is usually several addresses. One such address is an endpoint. Taking the list from Driving work over REST:

What it does	Method + endpoint
List tasks	`GET /api/v1/tasks`
Create a task	`POST /api/v1/tasks`
View one task	`GET /api/v1/tasks/{id}`
Stop it	`POST /api/v1/tasks/{id}/stop`

The method plus the address is the function. The same /tasks reads with GET and creates with POST. {id} marks where a real identifier goes.

REST and JSON

Two words describe most of today's APIs.

REST — the convention of "addresses are things, methods are actions". The table above is that shape.
JSON — the notation for what is exchanged. Text, readable by people too.

json

{  "id": "task_9f2",  "status": "running",  "prompt": "Summarise last week's returns data"}

How to read it continues in Shapes of data.

The key

Screens have logins. APIs have keys.

text

Authorization: Bearer sk_live_a1b2c3…

	Password	API key
Used by	a person	a program
How many	one	one per purpose
If lost	reset it	retire that key only

One per purpose is the whole point. If one leaks, you delete one thing. It is also why Calling it via API key insists on real names — without them you cannot tell which one to delete.

SDK — someone else's toolbox

Calling an API directly means building the URL, attaching headers and parsing the response. An SDK (library) is that work pre-wrapped per language.

text

by hand   build the URL → attach headers → parse the JSON responseSDK       client.tasks.create("…")

They do the same thing. Which is how Your machine as a model server can say "change only the base URL of the OpenAI SDK" — same counter shape, same toolbox.

Why call an API when a screen exists

text

□ The same job every day       → a schedule calls it instead of a person clicking□ Another system needs it      → the intranet or a Slack bot fetches it directly□ There are many of them       → nobody clicks 300 times□ It has to be on the record   → who called what is in the log

If the job is one case that needs human judgement, the screen is better. APIs are the tool for the opposite end.

What you have to respect when calling

Concept	Meaning	When you meet it
Rate limit	how many calls per period	a `429` response
Timeout	how long you will wait	long-running work
Retry	calling again after failure	careful with duplicate `POST`
Version	the `v1` in `/api/v1`	the shape changes, the old one stays

Common misconceptions

"Does opening an API expose our data?"

No. Only holders of a key can call it. But the key is the door, so key handling is the security question — see Accounts, passwords, API keys, permissions.

"Does having an API mean I need a developer?"

Something has to do the calling, yes. These days that something is often an agent writing the code, and MCP standardises the connection outright.

Check yourself

1. How do endpoints and methods relate?

Answer

The combination is the function. The same /tasks reads with GET and creates with POST.

2. Why issue one API key per purpose?

Answer

So a leak costs you only that key. Which is also why each needs a recognisable name.

3. Is an SDK something other than an API?

Answer

It is a toolbox for calling the same API — URL building, headers and parsing wrapped up per language.

Now see all of it with your own eyes → Take one request apart