1# api-design-principles — detailed patterns and worked examples
2 
3## REST API Design Patterns
4 
5### Pattern 1: Resource Collection Design
6 
7```python
8# Good: Resource-oriented endpoints
9GET    /api/users              # List users (with pagination)
10POST   /api/users              # Create user
11GET    /api/users/{id}         # Get specific user
12PUT    /api/users/{id}         # Replace user
13PATCH  /api/users/{id}         # Update user fields
14DELETE /api/users/{id}         # Delete user
15 
16# Nested resources
17GET    /api/users/{id}/orders  # Get user's orders
18POST   /api/users/{id}/orders  # Create order for user
19 
20# Bad: Action-oriented endpoints (avoid)
21POST   /api/createUser
22POST   /api/getUserById
23POST   /api/deleteUser
24```
25 
26### Pattern 2: Pagination and Filtering
27 
28```python
29from typing import List, Optional
30from pydantic import BaseModel, Field
31 
32class PaginationParams(BaseModel):
33    page: int = Field(1, ge=1, description="Page number")
34    page_size: int = Field(20, ge=1, le=100, description="Items per page")
35 
36class FilterParams(BaseModel):
37    status: Optional[str] = None
38    created_after: Optional[str] = None
39    search: Optional[str] = None
40 
41class PaginatedResponse(BaseModel):
42    items: List[dict]
43    total: int
44    page: int
45    page_size: int
46    pages: int
47 
48    @property
49    def has_next(self) -> bool:
50        return self.page < self.pages
51 
52    @property
53    def has_prev(self) -> bool:
54        return self.page > 1
55 
56# FastAPI endpoint example
57from fastapi import FastAPI, Query, Depends
58 
59app = FastAPI()
60 
61@app.get("/api/users", response_model=PaginatedResponse)
62async def list_users(
63    page: int = Query(1, ge=1),
64    page_size: int = Query(20, ge=1, le=100),
65    status: Optional[str] = Query(None),
66    search: Optional[str] = Query(None)
67):
68    # Apply filters
69    query = build_query(status=status, search=search)
70 
71    # Count total
72    total = await count_users(query)
73 
74    # Fetch page
75    offset = (page - 1) * page_size
76    users = await fetch_users(query, limit=page_size, offset=offset)
77 
78    return PaginatedResponse(
79        items=users,
80        total=total,
81        page=page,
82        page_size=page_size,
83        pages=(total + page_size - 1) // page_size
84    )
85```
86 
87### Pattern 3: Error Handling and Status Codes
88 
89```python
90from fastapi import HTTPException, status
91from pydantic import BaseModel
92 
93class ErrorResponse(BaseModel):
94    error: str
95    message: str
96    details: Optional[dict] = None
97    timestamp: str
98    path: str
99 
100class ValidationErrorDetail(BaseModel):
101    field: str
102    message: str
103    value: Any
104 
105# Consistent error responses
106STATUS_CODES = {
107    "success": 200,
108    "created": 201,
109    "no_content": 204,
110    "bad_request": 400,
111    "unauthorized": 401,
112    "forbidden": 403,
113    "not_found": 404,
114    "conflict": 409,
115    "unprocessable": 422,
116    "internal_error": 500
117}
118 
119def raise_not_found(resource: str, id: str):
120    raise HTTPException(
121        status_code=status.HTTP_404_NOT_FOUND,
122        detail={
123            "error": "NotFound",
124            "message": f"{resource} not found",
125            "details": {"id": id}
126        }
127    )
128 
129def raise_validation_error(errors: List[ValidationErrorDetail]):
130    raise HTTPException(
131        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
132        detail={
133            "error": "ValidationError",
134            "message": "Request validation failed",
135            "details": {"errors": [e.dict() for e in errors]}
136        }
137    )
138 
139# Example usage
140@app.get("/api/users/{user_id}")
141async def get_user(user_id: str):
142    user = await fetch_user(user_id)
143    if not user:
144        raise_not_found("User", user_id)
145    return user
146```
147 
148### Pattern 4: HATEOAS (Hypermedia as the Engine of Application State)
149 
150```python
151class UserResponse(BaseModel):
152    id: str
153    name: str
154    email: str
155    _links: dict
156 
157    @classmethod
158    def from_user(cls, user: User, base_url: str):
159        return cls(
160            id=user.id,
161            name=user.name,
162            email=user.email,
163            _links={
164                "self": {"href": f"{base_url}/api/users/{user.id}"},
165                "orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
166                "update": {
167                    "href": f"{base_url}/api/users/{user.id}",
168                    "method": "PATCH"
169                },
170                "delete": {
171                    "href": f"{base_url}/api/users/{user.id}",
172                    "method": "DELETE"
173                }
174            }
175        )
176```
177 
178## GraphQL Design Patterns
179 
180### Pattern 1: Schema Design
181 
182```graphql
183# schema.graphql
184 
185# Clear type definitions
186type User {
187  id: ID!
188  email: String!
189  name: String!
190  createdAt: DateTime!
191 
192  # Relationships
193  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!
194 
195  profile: UserProfile
196}
197 
198type Order {
199  id: ID!
200  status: OrderStatus!
201  total: Money!
202  items: [OrderItem!]!
203  createdAt: DateTime!
204 
205  # Back-reference
206  user: User!
207}
208 
209# Pagination pattern (Relay-style)
210type OrderConnection {
211  edges: [OrderEdge!]!
212  pageInfo: PageInfo!
213  totalCount: Int!
214}
215 
216type OrderEdge {
217  node: Order!
218  cursor: String!
219}
220 
221type PageInfo {
222  hasNextPage: Boolean!
223  hasPreviousPage: Boolean!
224  startCursor: String
225  endCursor: String
226}
227 
228# Enums for type safety
229enum OrderStatus {
230  PENDING
231  CONFIRMED
232  SHIPPED
233  DELIVERED
234  CANCELLED
235}
236 
237# Custom scalars
238scalar DateTime
239scalar Money
240 
241# Query root
242type Query {
243  user(id: ID!): User
244  users(first: Int = 20, after: String, search: String): UserConnection!
245 
246  order(id: ID!): Order
247}
248 
249# Mutation root
250type Mutation {
251  createUser(input: CreateUserInput!): CreateUserPayload!
252  updateUser(input: UpdateUserInput!): UpdateUserPayload!
253  deleteUser(id: ID!): DeleteUserPayload!
254 
255  createOrder(input: CreateOrderInput!): CreateOrderPayload!
256}
257 
258# Input types for mutations
259input CreateUserInput {
260  email: String!
261  name: String!
262  password: String!
263}
264 
265# Payload types for mutations
266type CreateUserPayload {
267  user: User
268  errors: [Error!]
269}
270 
271type Error {
272  field: String
273  message: String!
274}
275```
276 
277### Pattern 2: Resolver Design
278 
279```python
280from typing import Optional, List
281from ariadne import QueryType, MutationType, ObjectType
282from dataclasses import dataclass
283 
284query = QueryType()
285mutation = MutationType()
286user_type = ObjectType("User")
287 
288@query.field("user")
289async def resolve_user(obj, info, id: str) -> Optional[dict]:
290    """Resolve single user by ID."""
291    return await fetch_user_by_id(id)
292 
293@query.field("users")
294async def resolve_users(
295    obj,
296    info,
297    first: int = 20,
298    after: Optional[str] = None,
299    search: Optional[str] = None
300) -> dict:
301    """Resolve paginated user list."""
302    # Decode cursor
303    offset = decode_cursor(after) if after else 0
304 
305    # Fetch users
306    users = await fetch_users(
307        limit=first + 1,  # Fetch one extra to check hasNextPage
308        offset=offset,
309        search=search
310    )
311 
312    # Pagination
313    has_next = len(users) > first
314    if has_next:
315        users = users[:first]
316 
317    edges = [
318        {
319            "node": user,
320            "cursor": encode_cursor(offset + i)
321        }
322        for i, user in enumerate(users)
323    ]
324 
325    return {
326        "edges": edges,
327        "pageInfo": {
328            "hasNextPage": has_next,
329            "hasPreviousPage": offset > 0,
330            "startCursor": edges[0]["cursor"] if edges else None,
331            "endCursor": edges[-1]["cursor"] if edges else None
332        },
333        "totalCount": await count_users(search=search)
334    }
335 
336@user_type.field("orders")
337async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
338    """Resolve user's orders (N+1 prevention with DataLoader)."""
339    # Use DataLoader to batch requests
340    loader = info.context["loaders"]["orders_by_user"]
341    orders = await loader.load(user["id"])
342 
343    return paginate_orders(orders, first)
344 
345@mutation.field("createUser")
346async def resolve_create_user(obj, info, input: dict) -> dict:
347    """Create new user."""
348    try:
349        # Validate input
350        validate_user_input(input)
351 
352        # Create user
353        user = await create_user(
354            email=input["email"],
355            name=input["name"],
356            password=hash_password(input["password"])
357        )
358 
359        return {
360            "user": user,
361            "errors": []
362        }
363    except ValidationError as e:
364        return {
365            "user": None,
366            "errors": [{"field": e.field, "message": e.message}]
367        }
368```
369 
370### Pattern 3: DataLoader (N+1 Problem Prevention)
371 
372```python
373from aiodataloader import DataLoader
374from typing import List, Optional
375 
376class UserLoader(DataLoader):
377    """Batch load users by ID."""
378 
379    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
380        """Load multiple users in single query."""
381        users = await fetch_users_by_ids(user_ids)
382 
383        # Map results back to input order
384        user_map = {user["id"]: user for user in users}
385        return [user_map.get(user_id) for user_id in user_ids]
386 
387class OrdersByUserLoader(DataLoader):
388    """Batch load orders by user ID."""
389 
390    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
391        """Load orders for multiple users in single query."""
392        orders = await fetch_orders_by_user_ids(user_ids)
393 
394        # Group orders by user_id
395        orders_by_user = {}
396        for order in orders:
397            user_id = order["user_id"]
398            if user_id not in orders_by_user:
399                orders_by_user[user_id] = []
400            orders_by_user[user_id].append(order)
401 
402        # Return in input order
403        return [orders_by_user.get(user_id, []) for user_id in user_ids]
404 
405# Context setup
406def create_context():
407    return {
408        "loaders": {
409            "user": UserLoader(),
410            "orders_by_user": OrdersByUserLoader()
411        }
412    }
413```
414