API Design Guidelines

Overview

This skill provides guidelines for designing clean, consistent APIs. Apply these patterns when creating new endpoints, defining TypeScript interfaces, or reviewing API contracts.

Keywords: API design, REST, endpoints, TypeScript interfaces, data modeling, HTTP methods, response formats

REST Endpoint Design

URL Structure

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

Good examples:

• GET /users - List users
• GET /users/123 - Get user 123
• POST /users/123/orders - Create order for user 123

Avoid:

• /getUsers - Don't use verbs in URLs
• /user/list - Don't use action words
• /users/123/getOrders - HTTP method implies action

HTTP Methods

Method	Purpose	Idempotent	Body
GET	Read resource	Yes	No
POST	Create resource	No	Yes
PUT	Replace resource	Yes	Yes
PATCH	Update resource	No	Yes
DELETE	Remove resource	Yes	No

Response Codes

Success:

• 200 - OK (GET, PUT, PATCH with body)
• 201 - Created (POST)
• 204 - No Content (DELETE, PUT/PATCH without body)

Client errors:

• 400 - Bad Request (validation failed)
• 401 - Unauthorized (no/invalid auth)
• 403 - Forbidden (no permission)
• 404 - Not Found
• 409 - Conflict (duplicate, state conflict)
• 422 - Unprocessable Entity (semantic errors)

Server errors:

• 500 - Internal Server Error
• 503 - Service Unavailable

Response Formats

Success Response

// Single resource
{
  "data": {
    "id": "123",
    "name": "Example",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

// Collection
{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

Error Response

{
  "e...