REST APIs, explained from zero

What is an API?

An API (Application Programming Interface) is a contract that lets one program talk to another in a predictable way. Instead of opening a website in a browser, your app sends a structured request and gets a structured response back.

Think of a restaurant: you don’t walk into the kitchen. You use a menu (the API) to ask for what you want, and the kitchen returns a dish (the response).

What is REST?

REST (Representational State Transfer) is a popular style for designing web APIs. A REST API usually:

• Uses plain HTTP (the same protocol your browser already uses)
• Treats data as resources identified by URLs
• Uses standard methods (GET, POST, PUT, PATCH, DELETE) to say what to do
• Returns data in a portable format — most often JSON
• Is stateless: each request carries everything the server needs

You will often hear “REST API”, “RESTful API”, or simply “HTTP API”. In day-to-day work they refer to the same idea: call a URL with a method and get JSON back.

HTTP methods (the verbs)

The method tells the server what kind of action you want. Memorise these five:

GET    /users          → list users
GET    /users/42       → one user
POST   /users          → create user
PATCH  /users/42       → update user
DELETE /users/42       → delete user

URLs and resources

A REST URL points at a resource — a thing your API manages, such as /products, /orders, or /users/42.

• Collection: /products — many items
• Item: /products/17 — one item by id
• Nested: /users/42/orders — orders belonging to a user

Query parameters refine a request without changing the resource identity:

GET /products?count=20&category=shoes

Good REST URLs use nouns (resources), not verbs. Prefer POST /orders over /createOrder.

Status codes (how the server answers)

Every response includes a three-digit status code. Learn the families:

JSON request and response bodies

JSON (JavaScript Object Notation) is the most common data format for REST APIs. It looks like this:

{
  "id": 42,
  "name": "Ava Nkosi",
  "email": "ava@example.com",
  "active": true
}

On POST / PUT / PATCH you usually send JSON in the request body and set:

Content-Type: application/json

Arrays represent lists: [{...}, {...}]. Nested objects model related data.

Headers

Headers are metadata sent with every request or response. Important ones for beginners:

• Content-Type — what format the body uses (often application/json)
• Accept — what format you want back
• Authorization — credentials (for example a Bearer token)
• User-Agent — which client is calling

GET /v1/me HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGciOi...

Authentication (who are you?)

Public endpoints need no login. Protected endpoints require proof of identity:

• API keys — a secret string in a header or query param
• Bearer tokens — short-lived tokens after login (common with OAuth)
• Session cookies — the browser stores a cookie after sign-in
• Basic auth — username/password encoded in a header (rare for modern apps)

Never put long-lived secrets in frontend source code that anyone can download. Prefer server-side storage or short-lived tokens.

Idempotency and safety (bonus ideas)

• Safe methods (GET, HEAD) should not change server state.
• Idempotent methods (PUT, DELETE) can be repeated with the same end result.
• POST is usually not idempotent — calling it twice may create two records.

Practice with AOTG

Reading alone is not enough. AOTG lets you generate realistic JSON and stand up temporary mock REST endpoints so you can call them from Postman, curl, or your frontend.

# Example: call a mock collection (replace BASE with your mock URL)
curl "$BASE/products?count=5"

# Create an item
curl -X POST "$BASE/orders" \
  -H "Content-Type: application/json" \
  -d '{"total":42,"status":"pending"}'

Open the app Mock recipes AOTG OpenAPI Create a free account