api-design-principles — detailed patterns and worked examples
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
# schema.graphql# Clear type definitionstype 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-referenceuser: User!}# Pagination pattern (Relay-style)type OrderConnection {edges:[OrderEdge!]!pageInfo: PageInfo!totalCount: Int!}type OrderEdge {node: Order!cursor: String!}type PageInfo {hasNextPage: Boolean!hasPreviousPage: Boolean!startCursor: String
endCursor: String
}# Enums for type safetyenum OrderStatus {
PENDING
CONFIRMED
SHIPPED
DELIVERED
CANCELLED
}# Custom scalarsscalar DateTime
scalar Money
# Query roottypeQuery{
user(id: ID!): User
users(first: Int =20, after: String, search: String): UserConnection!
order(id: ID!): Order
}# Mutation roottypeMutation{
createUser(input: CreateUserInput!): CreateUserPayload!
updateUser(input: UpdateUserInput!): UpdateUserPayload!
deleteUser(id: ID!): DeleteUserPayload!
createOrder(input: CreateOrderInput!): CreateOrderPayload!}# Input types for mutationsinput CreateUserInput {email: String!name: String!password: String!}# Payload types for mutationstype CreateUserPayload {user: User
errors:[Error!]}type Error {field: String
message: String!}
Pattern 2: Resolver Design
from typing importOptional, Listfrom ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass
query = QueryType()
mutation = MutationType()
user_type = ObjectType("User")
@query.field("user")asyncdefresolve_user(obj, info, id: str) -> Optional[dict]:
"""Resolve single user by ID."""returnawait fetch_user_by_id(id)
@query.field("users")asyncdefresolve_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 else0# Fetch users
users = await fetch_users(
limit=first + 1, # Fetch one extra to check hasNextPage
offset=offset,
search=search
)
# Pagination
has_next = len(users) > first
if has_next:
users = users[:first]
edges = [
{
"node": user,
"cursor": encode_cursor(offset + i)
}
for i, user inenumerate(users)
]
return {
"edges": edges,
"pageInfo": {
"hasNextPage": has_next,
"hasPreviousPage": offset > 0,
"startCursor": edges[0]["cursor"] if edges elseNone,
"endCursor": edges[-1]["cursor"] if edges elseNone
},
"totalCount": await count_users(search=search)
}
@user_type.field("orders")asyncdefresolve_user_orders(user: dict, info, first: int = 20) -> dict:
"""Resolve user's orders (N+1 prevention with DataLoader)."""# Use DataLoader to batch requests
loader = info.context["loaders"]["orders_by_user"]
orders = await loader.load(user["id"])
return paginate_orders(orders, first)
@mutation.field("createUser")asyncdefresolve_create_user(obj, info, input: dict) -> dict:
"""Create new user."""try:
# Validate input
validate_user_input(input)
# Create user
user = await create_user(
email=input["email"],
name=input["name"],
password=hash_password(input["password"])
)
return {
"user": user,
"errors": []
}
except ValidationError as e:
return {
"user": None,
"errors": [{"field": e.field, "message": e.message}]
}
Pattern 3: DataLoader (N+1 Problem Prevention)
from aiodataloader import DataLoader
from typing importList, OptionalclassUserLoader(DataLoader):
"""Batch load users by ID."""asyncdefbatch_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]
classOrdersByUserLoader(DataLoader):
"""Batch load orders by user ID."""asyncdefbatch_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"]
if user_id notin orders_by_user:
orders_by_user[user_id] = []
orders_by_user[user_id].append(order)
# Return in input orderreturn [orders_by_user.get(user_id, []) for user_id in user_ids]
# Context setupdefcreate_context():
return {
"loaders": {
"user": UserLoader(),
"orders_by_user": OrdersByUserLoader()
}
}