Building RESTful APIsLesson 3.1

REST API design principles every developer should know

REST constraints, resource naming, noun vs verb URLs, statelessness, URI design, plural nouns, nested resources, HTTP method semantics, idempotency

REST API Design Principles

REST (Representational State Transfer) is a set of constraints for designing networked APIs. The key rules that matter day-to-day:

1. Resources are nouns, not verbs

// Wrong — verbs in URLs
GET  /getUsers
POST /createUser
GET  /deleteUser?id=42

// Correct — nouns + HTTP verbs do the action
GET    /users
POST   /users
DELETE /users/42

2. Use plural nouns — /users not /user, even for single resources.

3. Nest related resources — /users/42/posts for posts belonging to user 42. Limit nesting to 2 levels maximum.

4. Statelessness — each request must contain everything needed to process it. No session state on the server. Authentication credentials go in every request via headers.

5. Idempotency — GET, PUT, and DELETE are idempotent (same request, same result). POST is not. This matters for retries and caching.

Following these rules means developers can predict your API's behavior before reading docs — endpoints are discoverable and consistent.