Api Designer

API Designer

Design robust, scalable, and developer-friendly APIs.

Core Principles

1. Developer Experience First

• Clear, predictable naming conventions
• Comprehensive documentation
• Helpful error messages
• Consistent patterns across endpoints

2. Design for Evolution

• Versioning strategy from day one
• Backward compatibility
• Deprecation process
• Migration guides for breaking changes

3. Security by Default

• Authentication and authorization
• Rate limiting and throttling
• Input validation and sanitization
• HTTPS only, no exceptions

4. Performance Matters

• Efficient queries and indexing
• Caching strategies
• Pagination for large datasets
• Compression (gzip, brotli)

REST API Design

Resource Naming Conventions

✅ Good (Nouns, plural, hierarchical):
GET    /users                  # List all users
GET    /users/123              # Get specific user
POST   /users                  # Create user
PUT    /users/123              # Replace user
PATCH  /users/123              # Update user
DELETE /users/123              # Delete user
GET    /users/123/posts        # User's posts (nested)
GET    /users/123/posts/456    # Specific post

❌ Bad (Verbs, inconsistent, unclear):
GET /getUsers
POST /createUser
GET /user-list
GET /UserData?id=123

HTTP Methods & Semantics

Idempotent: Multiple identical requests have same effect as single request Safe: Request doesn't modify server state

HTTP Status Codes

Success (2xx):

• 200 OK - Successful GET, PUT, PATCH, DELETE
• 201 Created - Successful POST, includes Location header
• 204 No Content - Successful request, no response body (often DELETE)

Client Errors (4xx):

• 400 Bad Request - Invalid syntax, validation error
• 401 Unauthorized - Authentication required or failed
• 403 Forbidden - Authenticated but lacks permission
• 404 Not Found - Resource doesn't exist
• 409 Conflict - Request conflicts with current state
• 422 Unprocessable Entity - Validation error (semantic)
• 429 Too Many Requests - Rate limit exceeded

Server Errors (5xx):

• 500 Internal Server Error - Generic server error
• 502 Bad Gateway - Upstream service error
• 503 Service Unavailable - Temporary unavailability
• 504 Gateway Timeout - Upstream timeout

Response Format Standards

Success Response:

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2025-01-15T10:30:00Z"
    }
  }
}

Error Response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "REQUIRED",
        "message": "Email is required"
      },
      {
        "field": "age",
        "code": "OUT_OF_RANGE",
        "message": "Age must be between 18 and 120"
      }
    ],
    "request_id": "req_abc123",
    "documentation_url": "https://api.example.com/docs/errors/validation"
  }
}

List Response with Pagination:

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "total_count": 1000
  },
  "links": {
    "next": "/users?cursor=eyJpZCI6MTIzfQ==&limit=20",
    "prev": "/users?cursor=eyJpZCI6MTAwfQ==&limit=20"
  }
}

Pagination Strategies

Cursor-based (Recommended):

GET /users?cursor=abc123&limit=20

Pros: Consistent results, efficient, handles real-time data
Cons: Can't jump to arbitrary page
Use when: Large datasets, real-time data, performance critical

Offset-based:

GET /users?page=1&per_page=20
GET /users?offset=0&limit=20

Pros: Simple, can jump to any page
Cons: Inconsistent with concurrent writes, inefficient at scale
Use when: Small datasets, admin interfaces, simple use cases

Filtering, Sorting, and Search

Filtering:

GET /users?status=active&role=admin&created_after=2025-01-01

Sorting:

GET /users?sort=-created_at,name  # Descending created_at, then ascending name

Search:

GET /users?q=john&fields=name,email  # Search across specified fields

Authentication & Authorization

JWT Bearer Token (Recommended for SPAs):

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Pros: Stateless, includes user claims, works across domains
Cons: Can't revoke until expiry, larger payload

API Keys (for service-to-service):

X-API-Key: sk_live_abc123...

Pros: Simple, easy to rotate, per-service keys
Cons: No user context, must be kept secret

OAuth 2.0 (for third-party access):

Authorization: Bearer access_token

Pros: Delegated auth, scoped permissions, industry standard
Cons: Complex setup, requires OAuth server

Basic Auth (only for internal/admin tools):

Authorization: Basic base64(username:password)

Pros: Simple, built-in to HTTP
Cons: Credentials in every request, must use HTTPS

Rate Limiting

Standard Headers:

X-RateLimit-Limit: 1000          # Max requests per window
X-RateLimit-Remaining: 999       # Requests left
X-RateLimit-Reset: 1640995200    # Unix timestamp when limit resets
Retry-After: 60                  # Seconds to wait (on 429)

Common Strategies:

• Fixed window: 1000 requests per hour
• Sliding window: 1000 requests per rolling hour
• Token bucket: Burst allowance with refill rate
• Per-user, per-IP, or per-API-key limits

Versioning Strategies

URL Versioning (Recommended):

/v1/users
/v2/users

Pros: Explicit, easy to route, clear in logs
Cons: URL pollution, harder to evolve incrementally

Header Versioning:

Accept: application/vnd.myapp.v2+json
API-Version: 2

Pros: Clean URLs, follows REST principles
Cons: Less visible, harder to test in browser

Best Practices:

• Start with v1, not v0
• Only increment for breaking changes
• Support N and N-1 versions simultaneously
• Provide migration guides
• Announce deprecation 6-12 months ahead

---

GraphQL API Design

Schema Design

type User {
  id: ID!
  name: String!
  email: String!
  posts(first: Int, after: String): PostConnection!
  createdAt: DateTime!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type PostEdge {
  node: Post!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

type Query {
  user(id: ID!): User
  users(first: Int, after: String): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}

input CreateUserInput {
  name: String!
  email: String!
}

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

GraphQL Best Practices

1. Use Relay Connection Pattern for Pagination:

query {
  users(first: 10, after: "cursor") {
    edges {
      node {
        id
        name
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

2. Input Types for Mutations:

# ✅ Good: Input type + payload
mutation {
  createUser(input: { name: "John", email: "john@example.com" }) {
    user {
      id
      name
    }
    errors {
      field
      message
    }
  }
}

# ❌ Bad: Flat arguments
mutation {
  createUser(name: "John", email: "john@example.com") {
    id
    name
  }
}

3. Error Handling:

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

type CreateUserPayload {
  user: User # Null if errors
  errors: [Error!] # Field-level errors
}

type Error {
  field: String!
  code: String!
  message: String!
}

REST vs GraphQL Decision

Use REST when:

• Simple CRUD operations
• Caching is critical (HTTP caching)
• Public API for third-parties
• File uploads/downloads
• Team unfamiliar with GraphQL

Use GraphQL when:

• Clients need flexible queries
• Reducing over-fetching/under-fetching
• Rapid frontend iteration
• Complex nested data relationships
• Strong typing and schema benefits

---

API Documentation

OpenAPI/Swagger Specification

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users and posts
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserInput'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Documentation Best Practices

• ✅ Include request/response examples
• ✅ Document all error codes
• ✅ Provide authentication guides
• ✅ Interactive API playground (Swagger UI, GraphQL Playground)
• ✅ Code examples in multiple languages
• ✅ Rate limit information
• ✅ Changelog for API updates

---

Security Checklist

• [ ] HTTPS only (redirect HTTP → HTTPS)
• [ ] Authentication required for protected endpoints
• [ ] Authorization checks (user can only access own data)
• [ ] Input validation (schema validation, sanitization)
• [ ] Rate limiting per user/IP
• [ ] CORS configuration (whitelist origins)
• [ ] SQL injection prevention (parameterized queries)
• [ ] No sensitive data in URLs (use headers/body)
• [ ] Audit logging for sensitive operations
• [ ] API keys rotatable and revocable

---

Related Resources

Related Skills:

• frontend-builder - For consuming APIs from frontend
• deployment-advisor - For API hosting decisions
• performance-optimizer - For API performance tuning

Related Patterns:

• META/DECISION-FRAMEWORK.md - REST vs GraphQL decisions
• STANDARDS/architecture-patterns/api-gateway-pattern.md - API gateway architecture (when created)

Related Playbooks:

• PLAYBOOKS/deploy-api.md - API deployment procedure (when created)
• PLAYBOOKS/version-api.md - API versioning workflow (when created)

API Designer - Quick Start

Version: 1.0.0 Category: Technical Development Difficulty: Intermediate

What This Skill Does

Guides design of RESTful and GraphQL APIs with best practices for naming, versioning, authentication, error handling, and documentation.

When to Use

Use this skill when you need to:

• Design a new backend API
• Define API contracts and specifications
• Choose between REST and GraphQL
• Implement authentication and authorization
• Version an existing API
• Document API endpoints

Quick Start

Fastest path to a well-designed API:

1. Choose API style (REST vs GraphQL)

• REST: Simple CRUD, public API, caching critical
• GraphQL: Flexible queries, complex nested data, rapid frontend iteration

2. Design resources (REST) or schema (GraphQL)

• REST: Nouns, plural, hierarchical (/users/123/posts)
• GraphQL: Types, queries, mutations with input/payload pattern

3. Define authentication

• JWT Bearer: SPAs and mobile apps
• API Keys: Service-to-service
• OAuth 2.0: Third-party integrations

4. Implement core patterns

• Pagination: Cursor-based for scale
• Filtering: Query parameters
• Error handling: Structured error responses
• Versioning: URL versioning (/v1/users)

5. Document with OpenAPI/Swagger (REST) or GraphQL schema

• Include examples, error codes, auth guide
• Provide interactive playground

6. Add security & rate limiting

• HTTPS only
• Input validation
• Rate limits (1000 req/hour typical)

Time to first endpoint: 1-2 days for simple API, 1 week for comprehensive

File Structure

api-designer/
├── SKILL.md           # Main skill instructions (start here)
└── README.md          # This file

Prerequisites

Knowledge:

• HTTP protocol basics (methods, status codes, headers)
• JSON and data structures
• Basic security concepts (auth, tokens)

Tools:

• API development framework (Express, FastAPI, Next.js API routes)
• API documentation tool (Swagger UI, GraphQL Playground)
• API testing tool (Postman, Insomnia, curl)

Related Skills:

• None required, but frontend-builder helps for API consumption context

Success Criteria

You've successfully used this skill when:

• ✅ API follows REST conventions or GraphQL best practices
• ✅ All endpoints use proper HTTP methods and status codes
• ✅ Authentication and authorization implemented
• ✅ Pagination and filtering available for lists
• ✅ Error responses include helpful messages and field details
• ✅ API versioning strategy defined
• ✅ Rate limiting configured
• ✅ Complete API documentation published (OpenAPI or GraphQL schema)
• ✅ Security checklist completed

Common Workflows

Workflow 1: New REST API

1. Use api-designer to design resource structure 2. Define HTTP methods and status codes 3. Implement pagination and filtering 4. Add authentication (JWT Bearer) 5. Document with OpenAPI/Swagger 6. Use deployment-advisor for hosting

Workflow 2: New GraphQL API

1. Use api-designer to design schema (types, queries, mutations) 2. Implement Relay connection pattern for pagination 3. Use input/payload pattern for mutations 4. Add authentication resolver 5. Publish GraphQL Playground 6. Use deployment-advisor for hosting

Workflow 3: API Versioning

1. Use api-designer versioning strategy (URL-based) 2. Identify breaking changes 3. Create /v2 endpoints 4. Support v1 and v2 simultaneously 5. Announce v1 deprecation (6-12 months ahead) 6. Provide migration guide

Key Concepts

REST Principles:

• Resources: Nouns (users, posts), not verbs
• HTTP Methods: GET, POST, PUT, PATCH, DELETE
• Status Codes: 2xx success, 4xx client error, 5xx server error
• Idempotency: PUT, PATCH, DELETE should be idempotent

GraphQL Patterns:

• Schema-first: Define types, queries, mutations
• Relay Connections: Cursor-based pagination standard
• Input Types: For mutations (encapsulate arguments)
• Payload Types: Include data and errors

Authentication:

• JWT: Stateless, includes claims, works across domains
• API Keys: Simple, per-service, easy to rotate
• OAuth 2.0: Delegated auth, scoped permissions

Pagination:

• Cursor-based: Efficient, consistent, scales well (recommended)
• Offset-based: Simple, can jump to page, inefficient at scale

Versioning:

• URL: /v1/users, /v2/users (recommended)
• Header: API-Version: 2 or Accept: vnd.myapp.v2+json

Troubleshooting

Skill not activating?

• Try explicitly requesting: "Use the api-designer skill to..."
• Mention keywords: "API", "REST", "GraphQL", "endpoints", "authentication"

Choosing between REST and GraphQL?

• REST: Simple CRUD, public APIs, caching important, team familiarity
• GraphQL: Flexible queries, complex relationships, reducing over-fetching
• Can use both: REST for simple endpoints, GraphQL for complex queries

Status code confusion?

• 200: Success for GET, PUT, PATCH, DELETE
• 201: Success for POST (resource created)
• 204: Success with no response body (often DELETE)
• 400: Client error (validation, malformed request)
• 401: Authentication required or failed
• 403: Authenticated but no permission
• 404: Resource not found
• 422: Validation error (semantic)
• 429: Rate limit exceeded
• 500: Server error

Pagination strategy?

• Use cursor-based for large datasets, real-time data, performance
• Use offset-based for small datasets, admin interfaces, simplicity
• Cursor-based is generally recommended for production APIs

Authentication method?

• JWT Bearer: Web/mobile apps (SPAs, React Native)
• API Keys: Server-to-server, internal services
• OAuth 2.0: Third-party integrations, delegated access
• Never use Basic Auth except for internal admin tools with HTTPS

Versioning too complex?

• Start with /v1/ from day one
• Only increment for breaking changes (not additions)
• Support N and N-1 versions (two versions)
• Announce deprecation 6-12 months ahead
• Provide clear migration guides

Error messages unclear?

• Include error code for programmatic handling
• Provide human-readable message
• List field-level errors for validation
• Include request_id for debugging
• Link to documentation for error codes

Version History

• 1.0.0 (2025-10-21): Initial release, enhanced from api-designer skill with GraphQL and comprehensive REST guidance

License

Part of ai-dev-standards repository.