api-designer

What this skill does

# API Designer

## Overview

This skill provides comprehensive guidance for designing, documenting, and implementing modern APIs. It covers both REST and GraphQL paradigms, with emphasis on industry best practices, clear documentation, and maintainable architecture. Use this skill to create production-ready API designs that are scalable, secure, and developer-friendly.

## Core Capabilities

### REST API Design
- Resource-oriented endpoint design with proper URL structure
- HTTP method semantics and status code usage
- Request/response payload design with consistent naming
- Pagination, filtering, and sorting strategies
- Error handling and validation patterns

### GraphQL API Design
- Schema definition with type system and relationships
- Query and mutation design with proper input types
- Resolver patterns and performance optimization
- Fragment usage and directive implementation
- N+1 problem prevention strategies

### API Documentation
- OpenAPI 3.0 specification generation
- Interactive documentation with Swagger UI
- Authentication and authorization documentation
- Example requests/responses with multiple scenarios
- Code generation from specifications

### Authentication & Authorization
- OAuth 2.0 flows (authorization code, client credentials, PKCE)
- JWT token design, validation, and rotation
- API key management and rotation strategies
- Role-based access control (RBAC) implementation
- Rate limiting and throttling patterns

### API Versioning
- URL versioning and header-based versioning strategies
- Semantic versioning for API releases
- Deprecation planning and communication
- Backward compatibility maintenance
- Migration path design

## When to Use This Skill

Use this skill when:
- Designing a new API from scratch or refactoring existing endpoints
- Creating OpenAPI/Swagger specifications for documentation
- Implementing authentication and authorization flows
- Planning API versioning and deprecation strategies
- Designing GraphQL schemas and resolvers
- Establishing API governance and best practices

## REST API Design Workflow

### Step 1: Identify Resources

Identify core resources (nouns) your API will expose:

```
Resources: Users, Posts, Comments

Collections:
- GET    /users              (List all users)
- POST   /users              (Create new user)

Individual Resources:
- GET    /users/{id}         (Get specific user)
- PUT    /users/{id}         (Replace user - full update)
- PATCH  /users/{id}         (Update user - partial)
- DELETE /users/{id}         (Delete user)

Nested Resources:
- GET    /users/{id}/posts   (Get user's posts)
- POST   /users/{id}/posts   (Create post for user)
```

### Step 2: Design URL Structure

Follow RESTful naming conventions:

**Best Practices**:
- Use plural nouns: `/users`, `/posts` (not `/user`, `/post`)
- Use hyphens for multi-word: `/blog-posts` (not `/blogPosts` or `/blog_posts`)
- Keep URLs lowercase
- Limit nesting to 2 levels maximum
- Use query parameters for filtering: `/posts?status=published&author=123`

**Quick Examples**:
```
✅ Good:
GET /users
GET /users/123/posts
GET /posts?published=true&limit=10

❌ Bad:
GET /getUsers
GET /users/123/posts/comments/likes  (too deep nesting)
GET /posts/published  (use query param instead)
```

### Step 3: Choose HTTP Methods

Map operations to standard HTTP methods:

- **GET**: Retrieve resource(s) - Safe, idempotent, cacheable
- **POST**: Create new resource - Returns 201 Created with Location header
- **PUT**: Replace entire resource - Idempotent, full replacement
- **PATCH**: Partial update - Update specific fields only
- **DELETE**: Remove resource - Idempotent, returns 204 or 200

### Step 4: Design Request/Response Payloads

Structure JSON payloads consistently:

**Naming Conventions**:
- Use camelCase for JSON field names
- Use ISO 8601 for timestamps (UTC)
- Use consistent ID formats with prefixes: `usr_`, `post_`
- Include metadata: `createdAt`, `updatedAt`

**Example Response**:
```json
{
  "id": "usr_1234567890",
  "username": "johndoe",
  "email": "[email protected]",
  "profile": {
    "firstName": "John",
    "lastName": "Doe"
  },
  "createdAt": "2025-10-25T10:30:00Z",
  "updatedAt": "2025-10-25T10:30:00Z"
}
```

### Step 5: Implement Error Handling

Design comprehensive error responses:

**Error Response Format**:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid"
      }
    ],
    "requestId": "req_abc123xyz",
    "timestamp": "2025-10-25T10:30:00Z"
  }
}
```

**Key Status Codes**:
- `200 OK`: Successful GET, PUT, PATCH
- `201 Created`: Successful POST
- `204 No Content`: Successful DELETE
- `400 Bad Request`: Invalid request data
- `401 Unauthorized`: Missing/invalid authentication
- `403 Forbidden`: Authenticated but not authorized
- `404 Not Found`: Resource doesn't exist
- `422 Unprocessable Entity`: Validation errors
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Server error

### Step 6: Add Pagination and Filtering

**Cursor-Based Pagination** (recommended for large datasets):
```
GET /posts?limit=20&cursor=eyJpZCI6MTIzfQ

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTQzfQ",
    "hasMore": true
  }
}
```

**Offset-Based Pagination** (simpler for small datasets):
```
GET /posts?limit=20&offset=40&sort=-createdAt

Response:
{
  "data": [...],
  "pagination": {
    "total": 500,
    "limit": 20,
    "offset": 40
  }
}
```

For detailed pagination strategies and filtering patterns, see `references/rest_best_practices.md`.

## GraphQL API Design Workflow

### Step 1: Define Schema Types

Create type definitions for your domain:

```graphql
type User {
  id: ID!
  username: String!
  email: String!
  profile: Profile
  posts(limit: Int = 10): [Post!]!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  published: Boolean!
  author: User!
  tags: [String!]!
  createdAt: DateTime!
}
```

### Step 2: Design Queries

Define read operations with filtering:

```graphql
type Query {
  user(id: ID!): User
  post(id: ID!): Post

  users(
    limit: Int = 10
    offset: Int = 0
    search: String
  ): UserConnection!

  posts(
    limit: Int = 10
    published: Boolean
    authorId: ID
    tags: [String!]
  ): PostConnection!
}
```

### Step 3: Design Mutations

Define write operations with input types and error handling:

```graphql
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
  createPost(input: CreatePostInput!): CreatePostPayload!
}

input CreateUserInput {
  username: String!
  email: String!
  password: String!
}

type CreateUserPayload {
  user: User
  errors: [Error!]
}
```

For complete GraphQL schema examples, see `examples/graphql_schema.graphql`.

## Authentication Patterns

### OAuth 2.0 Quick Reference

**Authorization Code Flow** (web apps with backend):
```
1. Redirect to /oauth/authorize with client_id, redirect_uri, scope
2. User authenticates and grants permission
3. Receive authorization code via redirect
4. Exchange code for access token at /oauth/token
5. Use access token in Authorization header
```

**Client Credentials Flow** (service-to-service):
```
POST /oauth/token
{
  "grant_type": "client_credentials",
  "client_id": "CLIENT_ID",
  "client_secret": "SECRET"
}
```

**PKCE Flow** (mobile/SPA - most secure for public clients):
```
1. Generate code_verifier and code_challenge
2. Request authorization with code_challenge
3. Exchange code for token with code_verifier (no client_secret needed)
```

### JWT Token Design

**Token Structure**:
```json
{
  "header": { "alg": "RS256", "typ": "JWT" },
  "payload": {
    "sub": "usr_1234567890",
    "iat": 1698336000,
    "exp": 1698339600,
    "scope": ["read:posts", "write:posts"],
    "roles": ["user", "editor"]
  }
}
```

**Usage**:
`