REST API Design Principles That Stand the Test of Time

A well-designed REST API is intuitive, consistent, and a pleasure to use. Here are principles that lead to APIs developers love.

Resource Naming#

Use Nouns, Not Verbs#

❌ Bad
GET /getUsers
POST /createUser
PUT /updateUser/123
DELETE /deleteUser/123

✅ Good
GET /users
POST /users
PUT /users/123
DELETE /users/123

Use Plural Nouns#

❌ Inconsistent
GET /user/123
GET /users

✅ Consistent
GET /users/123
GET /users

Nest Resources Logically#

# User's posts
GET /users/123/posts
POST /users/123/posts

# Post's comments
GET /posts/456/comments
POST /posts/456/comments

# Avoid deep nesting (max 2 levels)
❌ /users/123/posts/456/comments/789/replies
✅ /comments/789/replies

HTTP Methods#

Method   | Usage                    | Idempotent | Safe
---------+--------------------------+------------+------
GET      | Retrieve resource(s)     | Yes        | Yes
POST     | Create resource          | No         | No
PUT      | Replace resource         | Yes        | No
PATCH    | Partial update           | No*        | No
DELETE   | Remove resource          | Yes        | No

* PATCH can be idempotent depending on implementation

Examples#

# Get all users
GET /users

# Get single user
GET /users/123

# Create user
POST /users
Content-Type: application/json

{"name": "John", "email": "john@example.com"}

# Replace user (full update)
PUT /users/123
Content-Type: application/json

{"name": "John Doe", "email": "johndoe@example.com"}

# Partial update
PATCH /users/123
Content-Type: application/json

{"name": "John Doe"}

# Delete user
DELETE /users/123

HTTP Status Codes#

Success Codes#

200 OK           - General success
201 Created      - Resource created (POST)
204 No Content   - Success, no body (DELETE)

Client Error Codes#

400 Bad Request     - Invalid input
401 Unauthorized    - No/invalid authentication
403 Forbidden       - Authenticated but not allowed
404 Not Found       - Resource doesn't exist
409 Conflict        - Resource conflict
422 Unprocessable   - Validation failed
429 Too Many Reqs   - Rate limited

Server Error Codes#

500 Internal Error  - Server error
502 Bad Gateway     - Upstream error
503 Unavailable     - Temporarily unavailable
504 Gateway Timeout - Upstream timeout

Error Responses#

Consistent Structure#

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      },
      {
        "field": "age",
        "message": "Must be a positive number"
      }
    ]
  }
}

Implementation#

class ApiError extends Error {
  constructor(
    public statusCode: number,
    public code: string,
    message: string,
    public details?: unknown[]
  ) {
    super(message);
  }

  toJSON() {
    return {
      error: {
        code: this.code,
        message: this.message,
        details: this.details,
      },
    };
  }
}

// Usage
throw new ApiError(400, 'VALIDATION_ERROR', 'Validation failed', [
  { field: 'email', message: 'Invalid email format' },
]);

Pagination#

Offset Pagination#

GET /users?offset=20&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "total": 100,
    "offset": 20,
    "limit": 10
  }
}

Cursor Pagination (Preferred)#

GET /users?cursor=abc123&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "def456",
    "hasMore": true
  }
}

Filtering, Sorting, and Fields#

# Filtering
GET /users?status=active&role=admin

# Sorting
GET /users?sort=created_at:desc,name:asc

# Field selection
GET /users?fields=id,name,email

# Combined
GET /users?status=active&sort=name:asc&fields=id,name&limit=10

Request/Response Design#

Consistent Envelopes#

// Single resource
{
  "data": {
    "id": "123",
    "name": "John"
  }
}

// Collection
{
  "data": [
    {"id": "123", "name": "John"},
    {"id": "456", "name": "Jane"}
  ],
  "pagination": {
    "total": 100,
    "nextCursor": "abc"
  }
}

Use Camel Case#

{
  "firstName": "John",
  "lastName": "Doe",
  "createdAt": "2024-01-15T10:30:00Z"
}

ISO 8601 for Dates#

{
  "createdAt": "2024-01-15T10:30:00Z",
  "scheduledFor": "2024-02-01T09:00:00-05:00"
}

Headers#

Request Headers#

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
X-Request-ID: <uuid>

Response Headers#

Content-Type: application/json
X-Request-ID: <uuid>
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Versioning#

URL Versioning (Recommended)#

GET /v1/users
GET /v2/users

Header Versioning#

GET /users
Accept: application/vnd.myapi.v1+json

HATEOAS (Optional)#

{
  "data": {
    "id": "123",
    "name": "John",
    "email": "john@example.com"
  },
  "links": {
    "self": "/users/123",
    "posts": "/users/123/posts",
    "followers": "/users/123/followers"
  }
}

Documentation#

# OpenAPI/Swagger
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive]
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

Conclusion#

Good REST API design is about consistency and predictability. Follow conventions, use proper HTTP methods and status codes, and document everything.

The best API is one where developers can guess the correct endpoint without reading documentation. Achieve that through consistent patterns applied throughout.

Share this article