Computing Foundations › APIs and the Web › Day 22

Day 22: What an API Is and Why Everything Has One

Day 22 of 365 — What an API Is and Why Everything Has One

After this lesson you will be able to explain what an API is as a contract between programs, name the parts of a request and response, and call several free public web APIs with curl — the exact skill that lets you reach a hosted model over HTTP.

Course
Computing Foundations
Category
APIs and the Web
Reading time
≈ 40 min
Practical time
≈ 30 min
Lesson duration
1h 10m
Last verified
2026-07-12

Hands-on lab for this lesson

Lab files on GitHub: https://github.com/ai-roadmap-365/ai-roadmap-365.github.io/tree/main/labs/sections/computing-foundations/day-022-what-an-api-is-and-why

  1. Get the hands-on files. Clone the labs repository once (you can reuse this clone for every lesson). This works on macOS, Linux, and Windows (PowerShell or WSL):
    git clone https://github.com/ai-roadmap-365/ai-roadmap-365.github.io.git
    cd ai-roadmap-365.github.io
  2. Open this lesson's lab. Move into the directory for this specific day. Every lab lives at the same predictable path — section / subsection / week / day:
    cd labs/sections/computing-foundations/day-022-what-an-api-is-and-why
  3. Read the lab guide. Open `README.md` in that directory. It lists the exact commands, what each does, the expected output, and how to check your work — read it before running anything.
  4. Run it and check your work. Follow the README's "How to run" section: run the example first to see the finished result, then complete the numbered exercises in `starter/`, then run the tests. The tests pass (exit 0) only when your work is correct.
    bash tests/run_tests.sh   # or the test command named in the lab README

You can also open the lab as a local page (works offline, shows the file tree and expected output).

Learning objectives

By the end of this lesson you will be able to:

Prerequisites

Why this matters


The idea in plain language


Historical background

Diagram: a library API compared with a web API


What it is — and what it is not

Diagram: what an API contract exposes compared with what it keeps private

It is:

It is not:


Why it was created and what problems it solves

Diagram: what each side of an API boundary gains from it


How it works

The endpoint: an address for an operation

Diagram: two programs and the API contract between them, with a request going in and a response coming out

The request

Diagram: the five parts of an API request

PartWhat it carriesExample
MethodThe verb — what kind of operationGET, POST
PathWhich resource/users/1
Query parametersOptions that refine it?_limit=5
HeadersMetadataAccept: application/json
BodyData sent with the request{"title":"Learn APIs"}

The response

Flowchart: a client sends a request to an endpoint, the server processes it and returns a response

Reading the documentation

Diagram: the method for learning a new API from its documentation


An everyday analogy

Ordering at a restaurant.

The restaurantThe API
The menuThe documentation
A dish nameAn endpoint
”No onions, extra rice”Query parameters
Your table numberYour credentials
The order slipThe request
The plate arrivingThe response
The kitchenThe implementation, hidden

Examples in practice


Implications: security, privacy, performance, scalability, and cost

Diagram: individual API calls in a loop compared with one batched request


Alternatives: free, open source, and commercial

Diagram: an official client library compared with raw HTTP calls

ApproachTypeWhere it fits
REST over HTTPThe defaultAlmost everything; Day 23 covers it properly
GraphQLFree, open sourceClients that need to choose their own response shape
gRPCFree, open sourceService-to-service calls where speed matters more than readability
WebSocketsBuilt inPersistent two-way channels, not request-response
WebhooksThe inverseThe server calls you — Day 26
SDK / client libraryUsually freeThe same API, wrapped, with retries and types included

TermWhat it actually is
APIThe published contract between two programs
EndpointOne URL the API answers at
ClientThe program making the request
ServerThe program answering it
PayloadThe body of a request or response
SDKA library wrapping an API in your language
ContractWhat both sides agreed, and what versioning protects

When to use it — and when not to

Diagram: using a documented API compared with scraping a page


The AI connection

Diagram: the shape of a request to a hosted model API


Knowledge check

quiz:
  question: "A service rewrites its entire backend — new language, new database, new servers — and existing client programs keep working with no changes. What made that possible?"
  options:
    - "The API contract stayed the same, and clients depend only on the contract"
    - "The clients were using an SDK that absorbed the changes"
    - "HTTP is stateless, so clients never noticed the servers changed"
    - "The new backend returned the same status codes as the old one"
  answer_index: 0
  explanation: "The contract is the whole point of the boundary: clients depend on the shape of requests and responses, never on what produces them. That is what lets everything behind the line be replaced without coordination."

Hands-on exercise

Call a real API, read its documentation, and compare what you got against what was promised. Worked through fully in the Day 22 lab directory.

What you are doingCommand
Fetch one resourcecurl https://jsonplaceholder.typicode.com/todos/1
See the content typecurl -I https://jsonplaceholder.typicode.com/todos/1
Refine with a parametercurl 'https://jsonplaceholder.typicode.com/todos?_limit=3'
Filter by fieldcurl 'https://jsonplaceholder.typicode.com/todos?userId=1'
Create somethingcurl -X POST -H 'Content-Type: application/json' -d '{"title":"Learn APIs"}' https://jsonplaceholder.typicode.com/todos
Ask for a missing resourcecurl -i https://jsonplaceholder.typicode.com/todos/99999

Expected output

{"userId":1,"id":1,"title":"delectus aut autem","completed":false}
Content-Type: application/json; charset=utf-8
HTTP/1.1 404 Not Found
{}

Validate your work

Troubleshooting

Common mistakes


Practice assignment


Extension challenge


Quiz

Q1. What is the best short description of an API?

  1. A program you download and install to speed up your computer
  2. The physical server that stores a website's data
  3. A contract for how one program asks another to do something
  4. A visual dashboard that humans click to use a service
Show answer

Answer: C. A contract for how one program asks another to do something

An API is an Application Programming Interface: an agreed contract describing the requests one program accepts and the responses it returns, while hiding how it is implemented. The server, the data, and a human dashboard are all different things.

Q2. Which kind of API is reached over HTTP across the network and is the focus of this week?

  1. A library API
  2. An operating-system (system-call) API
  3. A hardware API
  4. A web API
Show answer

Answer: D. A web API

A web API is a service on another computer that you call over HTTP, using the same request/response conversation your browser uses. Library and operating-system APIs are local — called within one machine — rather than across the network.

Q3. In a web API request, what is the endpoint?

  1. The specific URL the API answers at, one per resource
  2. The status code the server sends back
  3. The secret key that proves who is calling
  4. The JSON data returned in the response body
Show answer

Answer: A. The specific URL the API answers at, one per resource

An endpoint is a specific URL a web API answers at, such as /todos/1 or /users/1. The path names what you are asking about; the status code and body are parts of the response, not the endpoint.

Q4. Which list correctly names parts of an HTTP API request?

  1. Status code, headers, and body
  2. Method, path, parameters, headers, and body
  3. Latitude, longitude, and timestamp
  4. Client, server, and network
Show answer

Answer: B. Method, path, parameters, headers, and body

A request carries a method (the verb), a path/endpoint, query parameters that refine it, headers of metadata, and an optional body (payload). Status code, headers, and body describe the response, not the request.

Q5. You run `curl https://jsonplaceholder.typicode.com/todos/1` and get back `{"userId":1,"id":1,"title":"delectus aut autem","completed":false}`. What did you just do?

  1. Installed the JSONPlaceholder service on your computer
  2. Sent a secret API key to authenticate yourself
  3. Made a GET request to an endpoint and received a JSON response body
  4. Changed the data stored on the server
Show answer

Answer: C. Made a GET request to an endpoint and received a JSON response body

This is a complete API exchange: a GET request to the /todos/1 endpoint returns a 200 response whose JSON body has named fields. Nothing was installed, no key was sent, and GET only reads — it does not change server data.

Q6. Why does API documentation exist and need to be read for each new API?

  1. Because all APIs are identical, so one manual covers them all
  2. Because APIs are illegal to use without reading a legal notice first
  3. Because documentation is the program that runs the API
  4. Because every API defines its own endpoints and formats
Show answer

Answer: D. Because every API defines its own endpoints and formats

Each API defines its own set of endpoints, the parameters they accept, and the shape of their responses, so you read the docs to find the right endpoint and copy a working example. Documentation is a guide, not the running service, and APIs are not interchangeable.

Q7. A paid API returns HTTP 429 when your program calls it rapidly in a loop. What does that mean and why did it happen?

  1. You are rate-limited for calling too fast; slow down
  2. The server crashed; there is nothing you can do
  3. Your request body was malformed; fix the JSON
  4. The endpoint URL was misspelled; correct the path
Show answer

Answer: A. You are rate-limited for calling too fast; slow down

429 Too Many Requests signals a rate limit — a cap on requests per period that shared services enforce so no caller overwhelms them. A tight loop trips it; the fixes are to slow down, batch, or fetch fewer times. A malformed body is 400 and a bad path is usually 404.

Q8. What does it mean to describe an API "as a product" with public, partner, and internal audiences?

  1. The API is sold in physical stores
  2. The same interface can be public, partner, or internal
  3. Only public APIs are real APIs; partner and internal ones are fakes
  4. A product API cannot be reached over HTTP
Show answer

Answer: B. The same interface can be public, partner, or internal

Organizations treat APIs as products with different audiences: public APIs are open to any developer, partner APIs are shared with specific companies under agreement, and internal APIs connect a company's own systems. All are the same technical idea aimed at different callers.

Glossary

API
An Application Programming Interface: a defined contract by which one program asks another to do something, exposing the requests it accepts and responses it returns while hiding how it works inside.
web API
An API reached over HTTP across the network — a service on another computer your program calls with requests and reads responses from, instead of a local function.
endpoint
A specific URL that a web API answers at, usually standing for one resource or operation, such as /todos/1 or /users/1.
request
What a client sends to an API: a method (verb), a path/endpoint, optional query parameters, headers, and an optional body.
response
What the server sends back: a status code indicating the outcome, headers describing the answer, and a body carrying the data (usually JSON).
payload
The data carried in the body of a request or response — for example the JSON describing a thing to create in a POST, or the data returned in a response.
parameter
A value that refines a request, most often a query parameter appended after the path (such as ?userId=1) to filter or configure what the API returns.
client
The program that initiates an API call — it builds and sends the request and reads the response. Your curl command or your program is the client.
server
The machine and code that receives requests and fulfills them, implementing the API behind the contract while keeping its database and internals private.
REST
A widely used architectural style for web APIs, described by Roy Fielding in 2000, that maps operations onto HTTP methods and resource URLs (covered in depth on Day 23).
documentation
The human-written guide to an API that lists each endpoint, the parameters it accepts, and example requests and responses — what you read to learn how to call a new API.
JSON
JavaScript Object Notation, a simple text format of nested keys and values that is the near-universal way web APIs format their request and response bodies.
rate limit
A cap a service places on how many requests a caller may make per period; exceeding it returns HTTP 429 so that no single caller can overwhelm the shared service.
API key
A secret token a caller sends (usually in an Authorization header) to prove who they are; like a password, it must never be shared publicly or sent to an echo service.

Sources and further reading


Kept in this browser, no account needed. Your progress page turns the whole record into one link you can bookmark or open on another device.