API Design

Overview

• REST API Design - Resource-oriented endpoints, HTTP semantics, OpenAPI specs
• GraphQL Development - Schema-first design, resolvers, federation, DataLoader
• gRPC Services - Protocol Buffers, streaming patterns
• Python Library Architecture - Package structure, API design, SOLID principles
• Security & Performance - OAuth, JWT, rate limiting, caching

Quick Reference

RESTful Resource Design

• /api/v1/users

  (plural nouns, lowercase with hyphens)

• /api/v1/organizations/{org_id}/teams

  (hierarchical, max 2 levels)
• Never use verbs:

  /getUsers

  or underscores:

  /user_profiles

• GET

  - Retrieve resources (safe, idempotent, cacheable)

• POST

  - Create new resources (returns 201 with Location header)

• PUT

  - Replace entire resource (idempotent)

• PATCH

  - Partial update (only changed fields)

• DELETE

  - Remove resource (idempotent, returns 204)

HTTP Status Codes

• 200 OK

  - GET, PUT, PATCH success

• 201 Created

  - POST success (include Location header)

• 204 No Content

  - DELETE success

• 400 Bad Request

  - Malformed request

• 401 Unauthorized

  - Missing/invalid authentication

• 403 Forbidden

  - Insufficient permissions

• 404 Not Found

  - Resource doesn't exist

• 409 Conflict

  - Duplicate resource

• 422 Unprocessable Entity

  - Validation errors

• 429 Too Many Requests

  - Rate limit exceeded

• 500 Internal Server Error

  - Unhandled exception

• 503 Service Unavailable

  - Database/service down

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ],
    "requestId": "req_abc123",
    "timestamp": "2025-10-25T10:30:00Z"
  }
}

GraphQL Schema Design

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

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

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

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

FastAPI Route Pattern

from fastapi import APIRouter, Depends, HTTPException, status

router = APIRouter(prefix="/api/v1/users", tags=["users"])

@router.post("", response_model=UserRead, status_code=status.HTTP_201_CREATED)
async def create_user(
    user_data: UserCreate,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
) -> UserRead:
    """Create a new user in the current tenant."""
    repository = UserRepository(db, tenant_id=current_user.tenant_id)
    user = await repository.create(user_data)
    return user

Pydantic Schema Pattern

from pydantic import BaseModel, EmailStr, Field, ConfigDict

class UserCreate(BaseModel):
    """Schema for creating a new user."""
    email: EmailStr
    full_name: str = Field(..., min_length=1, max_length=255)
    password: str = Field(..., min_length=8)

class UserRead(BaseModel):
    """Schema for reading user data (public fields only)."""
    id: str
    tenant_id: str
    email: EmailStr
    full_name: str
    created_at: datetime

    model_config = ConfigDict(from_attributes=True)

Pagination Patterns

GET /posts?limit=20&cursor=eyJpZCI6MTIzfQ

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

GET /posts?limit=20&offset=40

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

Authentication Patterns

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

X-API-Key: sk_live_abc123def456

• Authorization Code Flow - Web apps with backend
• Client Credentials Flow - Service-to-service
• PKCE Flow - Mobile/SPA apps

Rate Limiting Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 75
X-RateLimit-Reset: 1698340800
Retry-After: 60

Available Resources

References

references/rest-best-practices.md

references/authentication.md

references/versioning-strategies.md

references/common-patterns.md

references/schema-patterns.md

references/federation-guide.md

references/performance-optimization.md

references/architectural-principles.md

references/pep-standards.md

references/fastapi-setup.md

references/openapi.md

references/error-handlers.md

references/cors-rate-limiting.md

references/openapi-spec.yaml

references/graphql-schema.graphql

references/grpc-service.proto

references/rate-limiting.yaml

references/api-security.yaml

Templates

templates/fastapi-crud-endpoint.py

templates/pydantic-schemas.py

templates/repository-pattern.py

templates/rate-limiter.py

templates/error-handler.py

templates/tanstack-server-function.ts

Examples

examples/fastapi-crud.md

examples/pydantic-schemas.md

examples/pagination.md

examples/testing.md

examples/tanstack-start.md

examples/openapi-spec.yaml

examples/graphql-schema.graphql

Scripts

scripts/schema_analyzer.py

scripts/resolver_generator.py

scripts/federation_scaffolder.py

scripts/api_helper.py

scripts/validate-api-spec.sh

Assets (Python Library)

assets/pyproject.toml.template

assets/README.md.template

assets/CONTRIBUTING.md.template

assets/project-structure.txt

assets/test-structure.txt

assets/example-exceptions.py

assets/example-config.py

Checklists

checklists/api-design-checklist.md

checklists/security-review.md

Core Workflows

1. Design a REST API

1. Identify resources (nouns): Users, Posts, Comments
2. Design URL structure with proper nesting
3. Choose appropriate HTTP methods
4. Define request/response schemas
5. Document with OpenAPI specification
6. Implement pagination and filtering
7. Add authentication and rate limiting

2. Build a GraphQL API

1. Define schema types with descriptions
2. Design queries with pagination (Relay connections)
3. Create mutations with input types and payloads
4. Implement DataLoader for N+1 prevention
5. Add authentication in resolvers
6. Configure caching and complexity limits

3. Set Up Apollo Federation

# Scaffold subgraphs
python scripts/federation_scaffolder.py users-service --entities User,Profile
python scripts/federation_scaffolder.py posts-service --entities Post --references User

# Configure gateway
python scripts/federation_scaffolder.py gateway --subgraphs users:4001,posts:4002

4. Validate API Specification

# Validate OpenAPI spec
python scripts/api_helper.py validate --spec openapi.yaml

# Analyze GraphQL schema
python scripts/schema_analyzer.py schema.graphql --validate

# Generate documentation
python scripts/api_helper.py docs --spec openapi.yaml --output docs/

Anti-Patterns to Avoid

1. Verb-Based URLs - Use

   /users

   not

   /getUsers

2. Inconsistent Response Envelopes - Always use consistent structure
3. Breaking Changes Without Versioning - Use semantic versioning
4. N+1 Queries in GraphQL - Use DataLoader for batching
5. Over-fetching REST Endpoints - Support sparse fieldsets
6. Missing Pagination - Always paginate list endpoints
7. No Idempotency Keys - Accept

   Idempotency-Key

   header for mutations
8. Leaky Internal Errors - Generic messages in production
9. Missing CORS Configuration - Configure allowed origins explicitly
10. No Rate Limiting - Implement per-user/per-endpoint limits

Quality Checklist

[ ] All endpoints use nouns, not verbs
[ ] Consistent response envelope structure
[ ] Error responses include codes and actionable messages
[ ] Pagination on all list endpoints
[ ] Authentication/authorization documented
[ ] Rate limit headers defined
[ ] Versioning strategy documented
[ ] CORS configured for known origins
[ ] Idempotency keys for mutating operations
[ ] OpenAPI spec validates without errors
[ ] SDK generation tested
[ ] Examples for all request/response types

When to Use This Skill

• Creating new API endpoints (REST, GraphQL, gRPC)
• Designing resource hierarchies and schemas
• Writing OpenAPI/Swagger specifications
• Implementing authentication and authorization
• Setting up pagination, filtering, and sorting
• Configuring rate limiting and CORS
• Designing Python library APIs
• Reviewing API designs in pull requests

Source Skills

api-design

• FastAPI, Pydantic, multi-tenant patterns
• Library structure, SOLID principles, PEP standards
• GraphQL, Apollo, Federation, DataLoader
• REST, gRPC, security, versioning
• Documentation, authentication, best practices