REST API Design: URLs, Status Codes, Pagination, and the Decisions That Actually Matter

REST API design has a lot of folklore ("always use nouns", "HATEOAS", "REST vs GraphQL") and a lot of pragmatics that matter more. This guide covers the decisions that actually affect how easy your API is to use and maintain.

URL Design

Use nouns, not verbs. The HTTP method provides the verb:

# Bad POST /getUser POST /createUser POST /deleteUser # Good GET /users/{id} POST /users DELETE /users/{id} 

Plural nouns for collections, singular for specific resources... though consistency matters more than the plural/singular choice. Pick one and stick to it:

GET /users # list GET /users/123 # single user POST /users # create PUT /users/123 # full update PATCH /users/123 # partial update DELETE /users/123 # delete 

Nested Resources

Use nesting for resources that only exist in the context of a parent:

GET /users/123/posts # all posts by user 123 POST /users/123/posts # create post for user 123 GET /users/123/posts/456 # specific post 

But don't nest deeper than 2 levels — it becomes unwieldy:

# This is too deep GET /users/123/posts/456/comments/789/likes 

For deep nesting, break the URL at a natural point:

# Better: use the resource directly with a filter GET /comments/789/likes GET /comments?postId=456 

HTTP Methods and Status Codes

Use the right method:

• GET: read, no side effects, cacheable
• POST: create, submit data
• PUT: replace entire resource
• PATCH: partial update
• DELETE: delete

Return the right status codes:

The 401 vs 403 distinction matters: 401 means "please authenticate", 403 means "you're authenticated but can't do this". Returning 401 for permission errors confuses clients.

Request and Response Format

Use JSON. Set Content-Type:

Content-Type: application/json Accept: application/json 

Response Structure

Be consistent. A simple flat structure is easier to consume than envelope-heavy patterns:

// Single resource { "id": 123, "name": "Alice", "email": "alice@example.com", "createdAt": "2024-01-15T10:30:00Z" } // Collection { "data": [ { "id": 123, "name": "Alice" }, { "id": 124, "name": "Bob" } ], "pagination": { "total": 150, "page": 1, "perPage": 20, "nextCursor": "eyJpZCI6MTI0fQ" } } // Error { "error": { "code": "VALIDATION_ERROR", "message": "Invalid input", "details": [ { "field": "email", "message": "Invalid email format" } ] } } 

Dates

Always use ISO 8601 in UTC. Never Unix timestamps (ambiguous, hard to read) or localized date strings:

{ "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T14:22:33Z" } 

Filtering, Sorting, Pagination

Use query parameters:

GET /articles?status=published&tag=firefox GET /articles?sort=publishedAt&order=desc GET /articles?page=2&perPage=20 GET /articles?cursor=eyJpZCI6MTI0fQ # cursor-based 

Cursor-based pagination is better than offset for large datasets:

• Offset pagination (page=3&perPage=20) breaks when items are added/deleted between requests
• Cursor pagination uses a stable reference point (usually the last seen ID)

// Cursor-based pagination const cursor = Buffer.from(JSON.stringify({ id: lastId })).toString('base64'); // Client passes: GET /articles?cursor=eyJpZCI6MTI0fQ&limit=20 // Server decodes and uses as WHERE id > lastId 

Versioning

Version your API from day one. Don't wait until you need to break something:

# URL versioning (most common) GET /v1/users GET /v2/users # Header versioning Accept: application/vnd.myapi.v2+json 

URL versioning is more explicit and easier to debug. Header versioning is "more correct" by REST semantics but harder for newcomers to discover.

Maintain backwards compatibility within a version. Don't change field names or remove fields in a patch — bump the version.

Authentication

For most APIs: JWT Bearer tokens.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 

For server-to-server: API keys.

Authorization: ApiKey sk_live_abc123 # or X-API-Key: sk_live_abc123 

Never put API keys or tokens in query strings — they appear in server logs.

Rate Limiting

Always rate limit. Return 429 Too Many Requests with retry guidance:

HTTP/1.1 429 Too Many Requests Retry-After: 60 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1705318200 

Rate limit headers help clients back off intelligently instead of hammering your server.

Error Handling

Return machine-readable error codes alongside human-readable messages:

{ "error": { "code": "USER_NOT_FOUND", "message": "No user with ID 999 exists", "requestId": "req_abc123" } } 

The code field lets clients handle specific errors programmatically. The message is for humans (logs, developer UIs). Include a requestId for production debugging.

Don't expose stack traces, SQL errors, or internal implementation details in API responses.

Idempotency

GET, PUT, and DELETE should be idempotent — calling them multiple times has the same effect as calling once.

For POST requests that should be idempotent (payment processing, sending emails), use an idempotency key:

POST /payments Idempotency-Key: a8098c1a-f86e-11da-bd1a-00112444be1e { "amount": 1000, "currency": "USD" } 

Store the key and return the same response for duplicate requests. Stripe uses this pattern.

Documentation

Document with OpenAPI/Swagger. Tools like Swagger UI auto-generate interactive documentation from your spec:

openapi: 3.0.0 info: title: My API version: 1.0.0 paths: /users/{id}: get: summary: Get user by ID parameters: - name: id in: path required: true schema: type: integer responses: '200': description: User found content: application/json: schema: $ref: '#/components/schemas/User'  '404': description: User not found 

The spec becomes the contract between frontend and backend. Generate client SDKs from it with openapi-generator.

Checklist

Before shipping an API:

• [ ] Consistent URL naming convention
• [ ] Correct HTTP methods and status codes
• [ ] ISO 8601 dates in UTC
• [ ] Error responses include machine-readable codes
• [ ] Authentication required where appropriate
• [ ] Rate limiting implemented
• [ ] Input validation with 400/422 on bad input
• [ ] No internal details in error responses
• [ ] API versioned from day one
• [ ] OpenAPI spec written or generated

Good API design is mostly consistency. The specific choices (plural vs singular, cursor vs offset pagination) matter less than applying them uniformly across your entire API surface.