REST API

REST (Representational State Transfer) is the most common style for building web APIs. It treats data (users, posts, products) as resources and uses standard HTTP methods.

Where REST Is Used

• Public web APIs (payments, shipping, maps, social media)
• Internal service APIs inside a company
• Mobile app backends (iOS/Android calling HTTP endpoints)

Industry Examples (Companies)

• GitHub: REST API for repos, issues, actions
• Stripe: REST API for payments and billing
• Shopify: REST Admin APIs (alongside GraphQL)

Resources (The “Nouns”)

A resource is a thing your API exposes.

Examples:

• users
• posts
• products
• orders

In REST, URLs usually represent resources (nouns), and the HTTP method represents the action (verb).

Good:

• GET /users (get a list of users)
• GET /users/42 (get user 42)

Avoid:

• GET /getUsers
• POST /createUser

Key Principles

1. Stateless: the server doesn’t remember client state between requests. Each request must include what it needs (like an auth token).
2. Client-Server: frontend (client) and backend (server) are separate and communicate via HTTP.
3. Uniform Interface: resources are identified by URLs (e.g., /users/1).

HTTP Methods

• GET: retrieve data (read)
• POST: create new data (create)
• PUT: replace existing data (all fields)
• PATCH: update existing data (some fields)
• DELETE: remove data

Routing (Endpoints)

Routing maps an incoming request (method + URL) to a handler.

An endpoint is a specific route, like GET /users/42.

Most REST APIs follow a predictable route pattern:

Resource operation	HTTP	Route
List resources	GET	/users
Create resource	POST	/users
Get one resource	GET	/users/:id
Replace one resource	PUT	/users/:id
Update one resource	PATCH	/users/:id
Delete one resource	DELETE	/users/:id

Where :id is a route parameter (a placeholder inside the URL).

Query Parameters (Filtering, Sorting, Pagination)

Query params come after ? and are great for searching and listing.

Examples:

• GET /users?role=admin (filter)
• GET /users?sort=-createdAt (sort descending)
• GET /users?page=2&limit=20 (pagination)

Rule of thumb:

• Use route params for identifying a single resource: /users/42
• Use query params for modifying a collection query: /users?role=admin

Nested Resources

Some resources belong to others. Example: a user has many posts.

• GET /users/42/posts (all posts for user 42)
• POST /users/42/posts (create a post for user 42)

Example Routes + Responses

List users

GET /users

[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob" }
]

Get one user

GET /users/1

{ "id": 1, "name": "Alice" }

Create a user

POST /users

{ "id": 3, "name": "Charlie" }

Idempotency (Quick Concept)

Some methods are designed so repeating the same request has the same effect:

• GET is idempotent (reading doesn’t change the server)
• PUT is usually idempotent (replace with the same representation repeatedly)
• DELETE is usually idempotent (deleting something twice keeps it deleted)
• POST is usually not idempotent (posting twice often creates two resources)

Status Codes

• 200 OK: success
• 201 Created: successfully created
• 400 Bad Request: client sent wrong data
• 401 Unauthorized: you need to log in
• 404 Not Found: resource doesn’t exist
• 500 Internal Server Error: the server crashed or had a bug

OpenAPI

Most REST APIs use an API spec for documentation and tooling. See:

• OpenAPI (Swagger)

References

• RESTful API Design
• MDN HTTP Methods