REST API Basics

Overview

REST (Representational State Transfer) is a style for building web APIs around resources — things like users, posts, or orders — each identified by a URL. Clients interact with those resources using standard HTTP methods, and the server responds with a representation (usually JSON). REST matters because its conventions are predictable: once you learn them, most APIs feel familiar.

Syntax / Usage

Resources are nouns, not verbs. You act on them with HTTP methods, and nesting shows relationships. A collection endpoint returns many items; an item endpoint returns one.

GET    /users          # list users
POST   /users          # create a user
GET    /users/42       # read one user
PUT    /users/42       # replace user 42
DELETE /users/42       # delete user 42
GET    /users/42/posts # posts belonging to user 42

Examples

Fetching a single resource returns its JSON representation:

GET /users/42 HTTP/1.1
Host: api.example.com
Accept: application/json

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

Creating a resource sends a body and gets the new record back:

POST /users HTTP/1.1
Content-Type: application/json

{ "name": "Grace Hopper", "email": "grace@example.com" }

{
  "id": 43,
  "name": "Grace Hopper",
  "email": "grace@example.com"
}

Common Mistakes

• Putting verbs in URLs (/getUser, /createUser) instead of using HTTP methods
• Using plural and singular inconsistently (/user/42 vs /users)
• Returning HTTP 200 for everything, including errors
• Embedding actions as query params (/users?action=delete) instead of DELETE
• Making endpoints stateful by relying on server-side session order

See Also

api-design-http-methods api-design-status-codes api-design-versioning