API Designer

Design consistent, intuitive, and well-documented APIs.

When to Use

• Designing new API endpoints

• Reviewing existing API structure

• Creating API documentation

• Planning API versioning strategy

• Designing error responses

REST API Design Principles

URL Structure

GET /resources # List resources GET /resources/:id # Get single resource POST /resources # Create resource PUT /resources/:id # Replace resource PATCH /resources/:id # Update resource partially DELETE /resources/:id # Delete resource

Naming Conventions

• Use nouns for resources: /users , /orders , /products

• Use plural form: /users not /user

• Use kebab-case for multi-word: /order-items

• Use path params for identification: /users/:id

• Use query params for filtering: /users?status=active

Nested Resources

GET /users/:userId/orders # User's orders GET /users/:userId/orders/:orderId # Specific order POST /users/:userId/orders # Create order for user

Keep nesting shallow (max 2 levels).

Request/Response Design

Request Body

{ "name": "John Doe", "email": "john@example.com", "preferences": { "newsletter": true, "theme": "dark" } }

• Use camelCase for property names

• Required fields should be documented

• Include validation constraints

Success Response

{ "data": { "id": "123", "name": "John Doe", "email": "john@example.com", "createdAt": "2026-01-15T10:30:00Z" } }

List Response with Pagination

{ "data": [ { "id": "1", "name": "Item 1" }, { "id": "2", "name": "Item 2" } ], "meta": { "page": 1, "perPage": 20, "total": 100, "totalPages": 5 }, "links": { "self": "/items?page=1", "next": "/items?page=2", "last": "/items?page=5" } }

Error Response (RFC 7807)

{ "type": "https://api.example.com/errors/validation", "title": "Validation Error", "status": 400, "detail": "The request body contains invalid data", "instance": "/users/123", "errors": [ { "field": "email", "message": "Invalid email format" } ] }

HTTP Status Codes

Success (2xx)

Code Use When

200 OK Request succeeded (GET, PUT, PATCH)

201 Created Resource created (POST)

204 No Content Success with no body (DELETE)

Client Errors (4xx)

Code Use When

400 Bad Request Malformed request / validation error

401 Unauthorized Missing or invalid authentication

403 Forbidden Authenticated but not authorized

404 Not Found Resource doesn't exist

409 Conflict Resource conflict (duplicate)

422 Unprocessable Valid syntax but semantic error

429 Too Many Requests Rate limit exceeded

Server Errors (5xx)

Code Use When

500 Internal Error Unexpected server error

502 Bad Gateway Upstream service error

503 Unavailable Service temporarily unavailable

API Versioning

URL Path (Recommended)

/v1/users /v2/users

Header-based

Accept: application/vnd.api+json; version=1

Authentication

Bearer Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key

X-API-Key: sk_live_abc123...

Documentation Template

Create User

Creates a new user account.

Request

POST /v1/users

Headers

Body

Example

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

Response

201 Created

```json { "data": { "id": "usr_123", "name": "John Doe", "email": "john@example.com", "createdAt": "2026-01-15T10:30:00Z" } } ```

400 Bad Request

```json { "type": "validation_error", "title": "Validation Error", "status": 400, "errors": [ { "field": "email", "message": "Email already exists" } ] } ```

Design Checklist

• Resource names are nouns, plural

• HTTP methods used correctly

• Consistent response format

• Proper status codes

• Pagination for lists

• Versioning strategy defined

• Authentication documented

• Error format standardized

• Rate limiting documented