api-design-principles

name	api-design-principles
description	Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

API Design Principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

When to Use This Skill

• Designing new REST or GraphQL APIs
• Refactoring existing APIs for better usability
• Establishing API design standards for your team
• Reviewing API specifications before implementation
• Migrating between API paradigms (REST to GraphQL, etc.)
• Creating developer-friendly API documentation
• Optimizing APIs for specific use cases (mobile, third-party integrations)

Core Concepts

1. RESTful Design Principles

Resource-Oriented Architecture

• Resources are nouns (users, orders, products), not verbs
• Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
• URLs represent resource hierarchies
• Consistent naming conventions

HTTP Methods Semantics:

• GET: Retrieve resources (idempotent, safe)
• POST: Create new resources
• PUT: Replace entire resource (idempotent)
• PATCH: Partial resource updates
• DELETE: Remove resources (idempotent)

2. GraphQL Design Principles

Schema-First Development

• Types define your domain model
• Queries for reading data
• Mutations for modifying data
• Subscriptions for real-time updates

Query Structure:

• Clients request exactly what they need
• Single endpoint, multiple operations
• Strongly typed schema
• Introspection built-in

3. API Versioning Strategies

URL Versioning:

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

Header Versioning:

Accept: application/vnd.api+json; version=1

Query Parameter Versioning:

/api/users?version=1

REST API Design Patterns

Pattern 1: Resource Collection Design

# Good: Resource-oriented endpoints
GET    /api/users              # List users (with pagination)
POST   /api/users              # Create user
GET    /api/users/{id}         # Get specific user
PUT    /api/users/{id}         # Replace user
PATCH  /api/users/{id}         # Update user fields
DELETE /api/users/{id}         # Delete user

# Nested resources
GET    /api/users/{id}/orders  # Get user's orders
POST   /api/users/{id}/orders  # Create order for user

# Bad: Action-oriented endpoints (avoid)
POST   /api/createUser
POST   /api/getUserById
POST   /api/deleteUser

Pattern 2: Pagination and Filtering

from typing import List, Optional
from pydantic import BaseModel, Field

class PaginationParams(BaseModel):
    page: int = Field(1, ge=1, description="Page number")
    page_size: int = Field(20, ge=1, le=100, description="Items per page")

class FilterParams(BaseModel):
    status: Optional[str] = None
    created_after: Optional[str] = None
    search: Optional[str] = None

class PaginatedResponse(BaseModel):
    items: List[dict]
    total: int
    page: int
    page_size: int
    pages: int

    @property
    def has_next(self) -> bool:
        return self.page < self.pages

    @property
    def has_prev(self) -> :
         .page > 


 fastapi  FastAPI, Query, Depends

app = FastAPI()


  ():
    
    query = build_query(status=status, search=search)

    
    total =  count_users(query)

    
    offset = (page - ) * page_size
    users =  fetch_users(query, limit=page_size, offset=offset)

     PaginatedResponse(
        items=users,
        total=total,
        page=page,
        page_size=page_size,
        pages=(total + page_size - ) // page_size
    )

Pattern 3: Error Handling and Status Codes

from fastapi import HTTPException, status
from pydantic import BaseModel

class ErrorResponse(BaseModel):
    error: str
    message: str
    details: Optional[dict] = None
    timestamp: str
    path: str

class ValidationErrorDetail(BaseModel):
    field: str
    message: str
    value: Any

# Consistent error responses
STATUS_CODES = {
    "success": 200,
    "created": 201,
    "no_content": 204,
    "bad_request": 400,
    "unauthorized": 401,
    "forbidden": 403,
    "not_found": 404,
    "conflict": 409,
    "unprocessable": 422,
    "internal_error": 500
}

def raise_not_found(resource: str, id: str):
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail={
            "error": "NotFound",
            : ,
            : {: }
        }
    )

 ():
     HTTPException(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        detail={
            : ,
            : ,
            : {: [e.()  e  errors]}
        }
    )



  ():
    user =  fetch_user(user_id)
      user:
        raise_not_found(, user_id)
     user

Pattern 4: HATEOAS (Hypermedia as the Engine of Application State)

class UserResponse(BaseModel):
    id: str
    name: str
    email: str
    _links: dict

    @classmethod
    def from_user(cls, user: User, base_url: str):
        return cls(
            id=user.id,
            name=user.name,
            email=user.email,
            _links={
                "self": {"href": f"{base_url}/api/users/{user.id}"},
                "orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
                "update": {
                    "href": f"{base_url}/api/users/{user.id}",
                    "method": "PATCH"
                },
                "delete": {
                    "href": f"{base_url}/api/users/{user.id}",
                    "method": "DELETE"
                }
            }
        )

GraphQL Design Patterns

Pattern 1: Schema Design

# schema.graphql

# Clear type definitions
type User {
  id: ID!
  email: String!
  name: String!
  createdAt: DateTime!

  # Relationships
  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!

  profile: UserProfile
}

type Order {
  id: ID!
  status: OrderStatus!
  total: Money!
  items: [OrderItem!]!
  createdAt: DateTime!

  # Back-reference
  user: User!


 UserProfile 
   String
   String
   String


 OrderItem 
   ID
   String
   String
   Int
   Money



 OrderConnection 
   OrderEdge
   PageInfo
   Int


 OrderEdge 
   Order
   String


 PageInfo 
   Boolean
   Boolean
   String
   String



 OrderStatus 
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED



 DateTime
 Money


  
  user ID User
  users Int  ,  String,  String UserConnection

  order ID Order



  
  createUser CreateUserInput CreateUserPayload
  updateUser UpdateUserInput UpdateUserPayload
  deleteUser ID DeleteUserPayload

  createOrder CreateOrderInput CreateOrderPayload



 CreateUserInput 
   String
   String
   String



 CreateUserPayload 
   User
   Error


 Error 
   String
   String

Pattern 2: Resolver Design

from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass

query = QueryType()
mutation = MutationType()
user_type = ObjectType("User")

@query.field("user")
async def resolve_user(obj, info, id: str) -> Optional[dict]:
    """Resolve single user by ID."""
    return await fetch_user_by_id(id)

@query.field("users")
async def resolve_users(
    obj,
    info,
    first: int = 20,
    after: Optional[str] = None,
    search: Optional[str] = None
) -> dict:
    """Resolve paginated user list."""
    # Decode cursor
    offset = decode_cursor(after) if after else 0

    # Fetch users
    users = await fetch_users(
        limit=first + 1,  # Fetch one extra to check hasNextPage
        offset=offset,
        search=search
    )

    # Pagination
    has_next = (users) > first
     has_next:
        users = users[:first]

    edges = [
        {
            : user,
            : encode_cursor(offset + i)
        }
         i, user  (users)
    ]

     {
        : edges,
        : {
            : has_next,
            : offset > ,
            : edges[][]  edges  ,
            : edges[-][]  edges  
        },
        :  count_users(search=search)
    }


  () -> :
    
    
    loader = info.context[][]
    orders =  loader.load(user[])

     paginate_orders(orders, first)


  () -> :
    
    :
        
        validate_user_input()

        
        user =  create_user(
            email=[],
            name=[],
            password=hash_password([])
        )

         {
            : user,
            : []
        }
     ValidationError  e:
         {
            : ,
            : [{: e.field, : e.message}]
        }

Pattern 3: DataLoader (N+1 Problem Prevention)

from aiodataloader import DataLoader
from typing import List, Optional

class UserLoader(DataLoader):
    """Batch load users by ID."""

    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
        """Load multiple users in single query."""
        users = await fetch_users_by_ids(user_ids)

        # Map results back to input order
        user_map = {user["id"]: user for user in users}
        return [user_map.get(user_id) for user_id in user_ids]

class OrdersByUserLoader(DataLoader):
    """Batch load orders by user ID."""

    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
        """Load orders for multiple users in single query."""
        orders = await fetch_orders_by_user_ids(user_ids)

        # Group orders by user_id
        orders_by_user = {}
        for order in orders:
            user_id = order["user_id"]
             user_id   orders_by_user:
                orders_by_user[user_id] = []
            orders_by_user[user_id].append(order)

        
         [orders_by_user.get(user_id, [])  user_id  user_ids]


 ():
     {
        : {
            : UserLoader(),
            : OrdersByUserLoader()
        }
    }

Best Practices

REST APIs

1. Consistent Naming: Use plural nouns for collections (/users, not /user)
2. Stateless: Each request contains all necessary information
3. Use HTTP Status Codes Correctly: 2xx success, 4xx client errors, 5xx server errors
4. Version Your API: Plan for breaking changes from day one
5. Pagination: Always paginate large collections
6. Rate Limiting: Protect your API with rate limits
7. Documentation: Use OpenAPI/Swagger for interactive docs

GraphQL APIs

1. Schema First: Design schema before writing resolvers
2. Avoid N+1: Use DataLoaders for efficient data fetching
3. Input Validation: Validate at schema and resolver levels
4. Error Handling: Return structured errors in mutation payloads
5. Pagination: Use cursor-based pagination (Relay spec)
6. Deprecation: Use @deprecated directive for gradual migration
7. Monitoring: Track query complexity and execution time

Common Pitfalls

• Over-fetching/Under-fetching (REST): Fixed in GraphQL but requires DataLoaders
• Breaking Changes: Version APIs or use deprecation strategies
• Inconsistent Error Formats: Standardize error responses
• Missing Rate Limits: APIs without limits are vulnerable to abuse
• Poor Documentation: Undocumented APIs frustrate developers
• Ignoring HTTP Semantics: POST for idempotent operations breaks expectations
• Tight Coupling: API structure shouldn't mirror database schema

Resources

• references/rest-best-practices.md: Comprehensive REST API design guide
• references/graphql-schema-design.md: GraphQL schema patterns and anti-patterns
• references/api-versioning-strategies.md: Versioning approaches and migration paths
• assets/rest-api-template.py: FastAPI REST API template
• assets/graphql-schema-template.graphql: Complete GraphQL schema example
• assets/api-design-checklist.md: Pre-implementation review checklist
• scripts/openapi-generator.py: Generate OpenAPI specs from code