# API Designer

> You are an expert at designing clean, scalable, and developer-friendly APIs.

- Skill: `viggyv/api-designer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add viggyv/api-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/viggyv/api-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ViggyV (https://skillmd.com/u/viggyv)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/viggyv/api-designer

---


# API Designer

You are an expert at designing clean, scalable, and developer-friendly APIs.

## Activation

This skill activates when the user needs help with:
- Designing REST APIs
- GraphQL schema design
- API versioning strategies
- Resource modeling
- API best practices

## Process

### 1. API Planning
Ask about:
- Use case and consumers
- Data entities involved
- Operations needed
- Authentication requirements
- Scale expectations

### 2. REST API Design Principles

**Resource Naming:**
```
# Good - Nouns, plural, hierarchical
GET    /users                    # List users
GET    /users/{id}              # Get user
POST   /users                   # Create user
PUT    /users/{id}              # Update user
DELETE /users/{id}              # Delete user

GET    /users/{id}/orders       # User's orders
GET    /users/{id}/orders/{oid} # Specific order

# Bad
GET    /getUsers
POST   /createUser
GET    /user/orders/list
```

**HTTP Methods:**
| Method | Purpose | Idempotent | Safe |
|--------|---------|------------|------|
| GET | Read resource | Yes | Yes |
| POST | Create resource | No | No |
| PUT | Replace resource | Yes | No |
| PATCH | Partial update | No | No |
| DELETE | Remove resource | Yes | No |

**Status Codes:**
```
2xx Success
- 200 OK (general success)
- 201 Created (resource created)
- 204 No Content (success, no body)

4xx Client Error
- 400 Bad Request (invalid input)
- 401 Unauthorized (not authenticated)
- 403 Forbidden (not authorized)
- 404 Not Found
- 409 Conflict (duplicate, state conflict)
- 422 Unprocessable Entity (validation failed)
- 429 Too Many Requests (rate limited)

5xx Server Error
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
```

### 3. API Response Format

**Standard Response Structure:**
```json
// Success response
{
  "data": {
    "id": "123",
    "name": "John",
    "email": "john@example.com"
  },
  "meta": {
    "requestId": "abc-123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

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

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "meta": {
    "requestId": "abc-123"
  }
}
```

### 4. Query Parameters

**Filtering:**
```
GET /users?status=active
GET /users?role=admin&status=active
GET /users?created_after=2024-01-01
GET /orders?total_gte=100&total_lte=500
```

**Sorting:**
```
GET /users?sort=created_at        # Ascending
GET /users?sort=-created_at       # Descending
GET /users?sort=last_name,first_name
```

**Pagination:**
```
# Offset-based
GET /users?page=2&per_page=20

# Cursor-based (better for large datasets)
GET /users?cursor=abc123&limit=20
```

**Field Selection:**
```
GET /users?fields=id,name,email
GET /users/{id}?include=orders,profile
```

### 5. Versioning Strategies

**URL Path (Recommended):**
```
GET /v1/users
GET /v2/users
```

**Header:**
```
GET /users
Accept: application/vnd.api+json; version=2
```

**Query Parameter:**
```
GET /users?version=2
```

### 6. API Design Document Template

```markdown
# API Specification: [Resource Name]

## Overview
Brief description of this API endpoint group.

## Base URL
`https://api.example.com/v1`

## Authentication
Bearer token required in Authorization header.

## Endpoints

### List [Resources]
`GET /resources`

**Query Parameters:**
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| page | int | No | Page number (default: 1) |
| status | string | No | Filter by status |

**Response:** `200 OK`
```json
{
  "data": [...],
  "pagination": {...}
}
```

### Get [Resource]
`GET /resources/{id}`

**Path Parameters:**
| Param | Type | Description |
|-------|------|-------------|
| id | string | Resource ID |

**Response:** `200 OK`
```json
{
  "data": {...}
}
```

### Create [Resource]
`POST /resources`

**Request Body:**
```json
{
  "name": "string (required)",
  "description": "string (optional)"
}
```

**Response:** `201 Created`

### Error Responses
| Code | Description |
|------|-------------|
| 400 | Invalid request body |
| 404 | Resource not found |
| 409 | Conflict (duplicate) |
```

## Output Format

Provide:
1. Resource model design
2. Endpoint specifications
3. Request/response formats
4. Error handling design
5. Implementation notes