API Design Guide

Design Principles

• Consistency - Same patterns everywhere

• Predictability - Clients can guess behavior

• Simplicity - Easy to use correctly, hard to misuse

• Evolvability - Can change without breaking clients

REST API Design

URL Structure

/resources # Collection /resources/{id} # Single resource /resources/{id}/sub-resources # Nested resources

Good:

• /users/123/orders

• /products?category=electronics

• /search?q=keyword

Bad:

• /getUser/123

• /users/123/getOrders

• /api/v1/fetch-all-products

HTTP Methods

Method Use Case Idempotent

GET Read Yes

POST Create No

PUT Replace Yes

PATCH Partial update Yes

DELETE Remove Yes

Status Codes

Code Meaning When to Use

200 OK Successful GET, PUT, PATCH

201 Created Successful POST

204 No Content Successful DELETE

400 Bad Request Invalid input

401 Unauthorized Not authenticated

403 Forbidden Not authorized

404 Not Found Resource doesn't exist

409 Conflict State conflict (duplicate)

422 Unprocessable Validation failed

500 Server Error Unexpected error

Response Format

{ "data": { ... }, "meta": { "page": 1, "total": 100 } }

Error response:

{ "error": { "code": "VALIDATION_ERROR", "message": "Email is required", "details": [ { "field": "email", "message": "Required" } ] } }

Pagination

Offset-based:

/items?page=2&limit=20

Cursor-based (preferred for large datasets):

/items?cursor=abc123&limit=20

Filtering & Sorting

/products?category=electronics&minPrice=100 /products?sort=price&order=desc /products?fields=id,name,price

Versioning Strategies

Strategy Example Pros Cons

URL path /v1/users

Explicit, cacheable URL pollution

Header Accept-Version: v1

Clean URLs Less visible

Query param ?version=1

Easy to test Cache issues

Recommendation: URL path versioning for simplicity.

Authentication

Method Use Case

API Key Server-to-server, simple

JWT Stateless, distributed

OAuth 2.0 Third-party access

Session Traditional web apps

Rate Limiting

Include headers:

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1640000000

Documentation Requirements

Every endpoint needs:

• URL and method

• Authentication required?

• Request parameters (path, query, body)

• Response format with examples

• Error codes and meanings

• Rate limits

Common Mistakes

• Using verbs in URLs (/getUsers )

• Inconsistent naming (/users vs /Users )

• Returning 200 for errors

• No pagination on list endpoints

• Breaking changes without versioning

• Missing error details

• No rate limiting