API Design Skill

Skill Metadata

• Name: api-design
• Description: Design RESTful APIs with consistent conventions across all services
• User Invocable: Yes (via /api-design)

Overview

This skill guides the design of RESTful APIs for any backend service, ensuring consistency, security, and usability across all endpoints. The discipline is stack-agnostic: the examples below use TypeScript and Zod for concreteness, but the conventions apply equally to Python, Go, Java, or any other language.

API Design Principles

1. Resource-Based URLs

Good
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
DELETE /api/v1/users/:id

Avoid
GET    /api/v1/getUsers
POST   /api/v1/createUser
POST   /api/v1/deleteUser

2. Consistent Response Format

{
  "success": true,
  "data": {
    // Resource data
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

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

3. HTTP Status Codes

4. Versioning

/api/v1/users
/api/v2/users

Embed the version in the URL path. Never negotiate it via a header unless a downstream client framework forces you to.

5. Filtering, Sorting, Pagination

GET /api/v1/users?status=active&sort=-createdAt&page=1&limit=20

# Filter operators
?status=active           # Equality
?amount_gte=100         # Greater than or equal
?amount_lte=1000        # Less than or equal
?name_like=john         # Contains

# Sorting
?sort=name              # Ascending
?sort=-createdAt        # Descending (prefix with -)
?sort=status,-createdAt # Multiple fields

# Pagination
?page=1&limit=20        # Page-based
?cursor=abc123&limit=20 # Cursor-based

Service Conventions

Authentication

Authorization: Bearer <jwt-token>

Service Prefix Pattern

Each bounded context (service or module) owns a prefix. For example:

Replace the rows above with your own domains.

Endpoint Patterns

# Collection
GET    /api/v1/resources          # List (with pagination)
POST   /api/v1/resources          # Create

# Single resource
GET    /api/v1/resources/:id      # Get one
PUT    /api/v1/resources/:id      # Full update
PATCH  /api/v1/resources/:id      # Partial update
DELETE /api/v1/resources/:id      # Delete

# Nested resources
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/profile

# Actions (when CRUD does not fit)
POST   /api/v1/orders/:id/approve
POST   /api/v1/proposals/:id/vote

API Design Template

Endpoint Specification

## [Method] [Path]

**Description**: [What this endpoint does]

**Authentication**: Required/Optional/None

**Authorization**: [Role requirements]

### Request

**Headers**:
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

**Path Parameters**:
| Parameter | Type | Description |
|-----------|------|-------------|
| id | string | Resource UUID |

**Query Parameters**:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| page | number | 1 | Page number |
| limit | number | 20 | Items per page |

**Body**:
```json
{
  "field1": "string",
  "field2": 123
}

Response

Success (200):

{
  "success": true,
  "data": {
    "id": "uuid",
    "field1": "value"
  }
}

Errors:

Example

Request:

curl -X POST /api/v1/resources \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{"field1": "value"}'

Response:

{
  "success": true,
  "data": { "id": "123", "field1": "value" }
}

---

## Workflow

### Phase 1: Requirements
1. Identify the resource or action
2. Define operations needed
3. Identify related resources and dependencies

### Phase 2: Design
1. Define URL structure following the resource-based convention
2. Specify request and response formats
3. Document all error cases (including business-rule violations, not just HTTP errors)
4. Define authentication and authorization requirements

### Phase 3: Validation
1. Review against the conventions in this skill
2. Check security implications (input surfaces, auth gaps, sensitive field exposure)
3. Consider backward compatibility if the service is already deployed

### Phase 4: Documentation
1. Create endpoint specs using the template above
2. Add to the project's API documentation
3. Generate or update the OpenAPI schema

---

## DTO Patterns

### Request DTO
```typescript
// dto.ts
import { z } from 'zod';

export const CreateUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  name: z.string().min(1).max(100),
});

export type CreateUserDTO = z.infer<typeof CreateUserSchema>;

Adapt the validation library to your stack. The principle is the same: parse inputs at the boundary, reject early, produce typed domain objects.

Response DTO

export interface UserResponseDTO {
  id: string;
  email: string;
  name: string;
  createdAt: string;
  // Note: never include passwords or secrets in responses
}

export interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: ApiError;
  meta?: PaginationMeta;
}

Security Considerations

Input Validation

• Validate all inputs server-side, regardless of client-side validation
• Use a schema library (Zod, Joi, Yup, Pydantic, etc.) for type safety
• Sanitize strings to prevent XSS and injection
• Enforce string length limits at the schema layer

Rate Limiting

@Throttle({ default: { limit: 10, ttl: 60000 } }) // 10 req/min
@Post('login')
async login() {}

Apply tighter limits to auth and sensitive write endpoints. Read endpoints can be more permissive.

Sensitive Operations

• Require re-authentication (or step-up auth) for actions with irreversible effects
• Log all administrative operations with actor identity, timestamp, and parameters
• Implement idempotency keys for any operation that should not run twice (payments, emails, state transitions)

Invocation

Manual

/api-design [resource-name]

Example

/api-design orders

Output Artifacts

1. Endpoint Specifications: Detailed documentation using the template above
2. DTO Definitions: Request and response type definitions
3. Validation Schemas: Schema-library schemas for each input surface
4. OpenAPI Spec: Machine-readable API definition for tooling and documentation generation