REST APIs and Web Communication PatternsLesson 5.1

REST API design: principles every developer must know

resource-based URLs, nouns not verbs in URLs, HTTP methods as actions, statelessness, HATEOAS, URL hierarchy, collection vs item endpoints

REST API Design Principles

REST API URL structure and HTTP methods diagram

REST (Representational State Transfer) is a set of constraints for web APIs, not a formal specification. These constraints produce APIs that are predictable, scalable, and easy to consume without documentation.

Core principles

Resources, not actions. URLs identify resources (nouns). HTTP methods are the verbs. Putting verbs in URLs signals a non-REST design:

# Wrong — verb in URL
POST /createUser
GET  /getUserById?id=42
POST /deleteUser

# Correct — resource URL, method as verb
POST   /users          # create
GET    /users/42       # read
PUT    /users/42       # full replace
PATCH  /users/42       # partial update
DELETE /users/42       # delete

Statelessness. Each request contains all information needed to process it — no server-side session. Authentication credentials (token, API key) appear in every request header. Statelessness enables horizontal scaling: any server instance can handle any request without shared state.

Hierarchy expresses relationships.

GET /users/42/orders        # All orders for user 42
GET /users/42/orders/7      # Specific order of a specific user

Limit nesting to two levels. Deeply nested URLs create tight coupling between resources. If a resource is independently accessible, give it a top-level endpoint and use query parameters for filtering instead: GET /orders?userId=42.

Consistent naming. Use plural nouns (/users not /user), lowercase, hyphens over underscores for multi-word resources (/blog-posts).