← All Tutorials
Web Developmentintermediate10 min read

REST API Design Basics

Learn how to design clean, consistent REST APIs. Covers resource naming, HTTP methods, status codes, pagination, and versioning.

Core REST Principles

REST (Representational State Transfer) is an architectural style for APIs built on HTTP. Key principles:

  • Resources — everything is a resource identified by a URL
  • HTTP methods — use GET, POST, PUT, PATCH, DELETE with their intended semantics
  • Stateless — each request contains all the information needed; no server-side sessions
  • Uniform interface — consistent URL patterns and response formats across endpoints

URL Structure and Naming

Use nouns for resources, not verbs. Keep URLs predictable:

  • `GET /users` — list all users
  • `GET /users/42` — get user 42
  • `POST /users` — create a new user
  • `PUT /users/42` — replace user 42
  • `PATCH /users/42` — partially update user 42
  • `DELETE /users/42` — delete user 42

For nested resources: `GET /users/42/orders` — list orders for user 42. Avoid deep nesting beyond two levels.

Pagination and Filtering

For collections, always paginate. Common patterns:

# Offset-based pagination
GET /articles?page=2&per_page=25

# Cursor-based pagination (better for large datasets)
GET /articles?after=eyJpZCI6MTAwfQ&limit=25

# Filtering and sorting
GET /articles?status=published&sort=-created_at
GET /users?role=admin&search=alice

Versioning Your API

APIs evolve, and breaking changes need a versioning strategy:

  • URL path — `GET /v2/users` — simple, explicit, easy to route
  • Header — `Accept: application/vnd.api+json;version=2` — cleaner URLs but harder to test
  • Query param — `GET /users?version=2` — easy to use but pollutes the URL

URL path versioning is the most widely adopted approach. Only increment the major version for breaking changes.

Related Tutorials

HTTPbeginner

HTTP Status Codes Explained

A complete guide to HTTP response status codes. Learn what 200, 301, 404, 500, and other codes mean with real-world examples.

Web Development·10 min read
DNSbeginner

How DNS Works

Understand the Domain Name System from root servers to your browser. Learn about DNS resolution, record types, caching, and troubleshooting.

Networking·8 min read