1---
2name: api-design-principles
3description: 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.
4---
5 
6# API Design Principles
7 
8Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
9 
10## When to Use This Skill
11 
12- Designing new REST or GraphQL APIs
13- Refactoring existing APIs for better usability
14- Establishing API design standards for your team
15- Reviewing API specifications before implementation
16- Migrating between API paradigms (REST to GraphQL, etc.)
17- Creating developer-friendly API documentation
18- Optimizing APIs for specific use cases (mobile, third-party integrations)
19 
20## Core Concepts
21 
22### 1. RESTful Design Principles
23 
24**Resource-Oriented Architecture**
25 
26- Resources are nouns (users, orders, products), not verbs
27- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
28- URLs represent resource hierarchies
29- Consistent naming conventions
30 
31**HTTP Methods Semantics:**
32 
33- `GET`: Retrieve resources (idempotent, safe)
34- `POST`: Create new resources
35- `PUT`: Replace entire resource (idempotent)
36- `PATCH`: Partial resource updates
37- `DELETE`: Remove resources (idempotent)
38 
39### 2. GraphQL Design Principles
40 
41**Schema-First Development**
42 
43- Types define your domain model
44- Queries for reading data
45- Mutations for modifying data
46- Subscriptions for real-time updates
47 
48**Query Structure:**
49 
50- Clients request exactly what they need
51- Single endpoint, multiple operations
52- Strongly typed schema
53- Introspection built-in
54 
55### 3. API Versioning Strategies
56 
57**URL Versioning:**
58 
59```
60/api/v1/users
61/api/v2/users
62```
63 
64**Header Versioning:**
65 
66```
67Accept: application/vnd.api+json; version=1
68```
69 
70**Query Parameter Versioning:**
71 
72```
73/api/users?version=1
74```
75 
76## REST API Design Patterns
77 
78### Pattern 1: Resource Collection Design
79 
80```python
81# Good: Resource-oriented endpoints
82GET    /api/users              # List users (with pagination)
83POST   /api/users              # Create user
84GET    /api/users/{id}         # Get specific user
85PUT    /api/users/{id}         # Replace user
86PATCH  /api/users/{id}         # Update user fields
87DELETE /api/users/{id}         # Delete user
88 
89# Nested resources
90GET    /api/users/{id}/orders  # Get user's orders
91POST   /api/users/{id}/orders  # Create order for user
92 
93# Bad: Action-oriented endpoints (avoid)
94POST   /api/createUser
95POST   /api/getUserById
96POST   /api/deleteUser
97```
98 
99### Pattern 2: Pagination and Filtering
100 
101```python
102from typing import List, Optional
103from pydantic import BaseModel, Field
104 
105class PaginationParams(BaseModel):
106    page: int = Field(1, ge=1, description="Page number")
107    page_size: int = Field(20, ge=1, le=100, description="Items per page")
108 
109class FilterParams(BaseModel):
110    status: Optional[str] = None
111    created_after: Optional[str] = None
112    search: Optional[str] = None
113 
114class PaginatedResponse(BaseModel):
115    items: List[dict]
116    total: int
117    page: int
118    page_size: int
119    pages: int
120 
121    @property
122    def has_next(self) -> bool:
123        return self.page < self.pages
124 
125    @property
126    def has_prev(self) -> bool:
127        return self.page > 1
128 
129# FastAPI endpoint example
130from fastapi import FastAPI, Query, Depends
131 
132app = FastAPI()
133 
134@app.get("/api/users", response_model=PaginatedResponse)
135async def list_users(
136    page: int = Query(1, ge=1),
137    page_size: int = Query(20, ge=1, le=100),
138    status: Optional[str] = Query(None),
139    search: Optional[str] = Query(None)
140):
141    # Apply filters
142    query = build_query(status=status, search=search)
143 
144    # Count total
145    total = await count_users(query)
146 
147    # Fetch page
148    offset = (page - 1) * page_size
149    users = await fetch_users(query, limit=page_size, offset=offset)
150 
151    return PaginatedResponse(
152        items=users,
153        total=total,
154        page=page,
155        page_size=page_size,
156        pages=(total + page_size - 1) // page_size
157    )
158```
159 
160### Pattern 3: Error Handling and Status Codes
161 
162```python
163from fastapi import HTTPException, status
164from pydantic import BaseModel
165 
166class ErrorResponse(BaseModel):
167    error: str
168    message: str
169    details: Optional[dict] = None
170    timestamp: str
171    path: str
172 
173class ValidationErrorDetail(BaseModel):
174    field: str
175    message: str
176    value: Any
177 
178# Consistent error responses
179STATUS_CODES = {
180    "success": 200,
181    "created": 201,
182    "no_content": 204,
183    "bad_request": 400,
184    "unauthorized": 401,
185    "forbidden": 403,
186    "not_found": 404,
187    "conflict": 409,
188    "unprocessable": 422,
189    "internal_error": 500
190}
191 
192def raise_not_found(resource: str, id: str):
193    raise HTTPException(
194        status_code=status.HTTP_404_NOT_FOUND,
195        detail={
196            "error": "NotFound",
197            "message": f"{resource} not found",
198            "details": {"id": id}
199        }
200    )
201 
202def raise_validation_error(errors: List[ValidationErrorDetail]):
203    raise HTTPException(
204        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
205        detail={
206            "error": "ValidationError",
207            "message": "Request validation failed",
208            "details": {"errors": [e.dict() for e in errors]}
209        }
210    )
211 
212# Example usage
213@app.get("/api/users/{user_id}")
214async def get_user(user_id: str):
215    user = await fetch_user(user_id)
216    if not user:
217        raise_not_found("User", user_id)
218    return user
219```
220 
221### Pattern 4: HATEOAS (Hypermedia as the Engine of Application State)
222 
223```python
224class UserResponse(BaseModel):
225    id: str
226    name: str
227    email: str
228    _links: dict
229 
230    @classmethod
231    def from_user(cls, user: User, base_url: str):
232        return cls(
233            id=user.id,
234            name=user.name,
235            email=user.email,
236            _links={
237                "self": {"href": f"{base_url}/api/users/{user.id}"},
238                "orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
239                "update": {
240                    "href": f"{base_url}/api/users/{user.id}",
241                    "method": "PATCH"
242                },
243                "delete": {
244                    "href": f"{base_url}/api/users/{user.id}",
245                    "method": "DELETE"
246                }
247            }
248        )
249```
250 
251## GraphQL Design Patterns
252 
253### Pattern 1: Schema Design
254 
255```graphql
256# schema.graphql
257 
258# Clear type definitions
259type User {
260  id: ID!
261  email: String!
262  name: String!
263  createdAt: DateTime!
264 
265  # Relationships
266  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!
267 
268  profile: UserProfile
269}
270 
271type Order {
272  id: ID!
273  status: OrderStatus!
274  total: Money!
275  items: [OrderItem!]!
276  createdAt: DateTime!
277 
278  # Back-reference
279  user: User!
280}
281 
282# Pagination pattern (Relay-style)
283type OrderConnection {
284  edges: [OrderEdge!]!
285  pageInfo: PageInfo!
286  totalCount: Int!
287}
288 
289type OrderEdge {
290  node: Order!
291  cursor: String!
292}
293 
294type PageInfo {
295  hasNextPage: Boolean!
296  hasPreviousPage: Boolean!
297  startCursor: String
298  endCursor: String
299}
300 
301# Enums for type safety
302enum OrderStatus {
303  PENDING
304  CONFIRMED
305  SHIPPED
306  DELIVERED
307  CANCELLED
308}
309 
310# Custom scalars
311scalar DateTime
312scalar Money
313 
314# Query root
315type Query {
316  user(id: ID!): User
317  users(first: Int = 20, after: String, search: String): UserConnection!
318 
319  order(id: ID!): Order
320}
321 
322# Mutation root
323type Mutation {
324  createUser(input: CreateUserInput!): CreateUserPayload!
325  updateUser(input: UpdateUserInput!): UpdateUserPayload!
326  deleteUser(id: ID!): DeleteUserPayload!
327 
328  createOrder(input: CreateOrderInput!): CreateOrderPayload!
329}
330 
331# Input types for mutations
332input CreateUserInput {
333  email: String!
334  name: String!
335  password: String!
336}
337 
338# Payload types for mutations
339type CreateUserPayload {
340  user: User
341  errors: [Error!]
342}
343 
344type Error {
345  field: String
346  message: String!
347}
348```
349 
350### Pattern 2: Resolver Design
351 
352```python
353from typing import Optional, List
354from ariadne import QueryType, MutationType, ObjectType
355from dataclasses import dataclass
356 
357query = QueryType()
358mutation = MutationType()
359user_type = ObjectType("User")
360 
361@query.field("user")
362async def resolve_user(obj, info, id: str) -> Optional[dict]:
363    """Resolve single user by ID."""
364    return await fetch_user_by_id(id)
365 
366@query.field("users")
367async def resolve_users(
368    obj,
369    info,
370    first: int = 20,
371    after: Optional[str] = None,
372    search: Optional[str] = None
373) -> dict:
374    """Resolve paginated user list."""
375    # Decode cursor
376    offset = decode_cursor(after) if after else 0
377 
378    # Fetch users
379    users = await fetch_users(
380        limit=first + 1,  # Fetch one extra to check hasNextPage
381        offset=offset,
382        search=search
383    )
384 
385    # Pagination
386    has_next = len(users) > first
387    if has_next:
388        users = users[:first]
389 
390    edges = [
391        {
392            "node": user,
393            "cursor": encode_cursor(offset + i)
394        }
395        for i, user in enumerate(users)
396    ]
397 
398    return {
399        "edges": edges,
400        "pageInfo": {
401            "hasNextPage": has_next,
402            "hasPreviousPage": offset > 0,
403            "startCursor": edges[0]["cursor"] if edges else None,
404            "endCursor": edges[-1]["cursor"] if edges else None
405        },
406        "totalCount": await count_users(search=search)
407    }
408 
409@user_type.field("orders")
410async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
411    """Resolve user's orders (N+1 prevention with DataLoader)."""
412    # Use DataLoader to batch requests
413    loader = info.context["loaders"]["orders_by_user"]
414    orders = await loader.load(user["id"])
415 
416    return paginate_orders(orders, first)
417 
418@mutation.field("createUser")
419async def resolve_create_user(obj, info, input: dict) -> dict:
420    """Create new user."""
421    try:
422        # Validate input
423        validate_user_input(input)
424 
425        # Create user
426        user = await create_user(
427            email=input["email"],
428            name=input["name"],
429            password=hash_password(input["password"])
430        )
431 
432        return {
433            "user": user,
434            "errors": []
435        }
436    except ValidationError as e:
437        return {
438            "user": None,
439            "errors": [{"field": e.field, "message": e.message}]
440        }
441```
442 
443### Pattern 3: DataLoader (N+1 Problem Prevention)
444 
445```python
446from aiodataloader import DataLoader
447from typing import List, Optional
448 
449class UserLoader(DataLoader):
450    """Batch load users by ID."""
451 
452    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
453        """Load multiple users in single query."""
454        users = await fetch_users_by_ids(user_ids)
455 
456        # Map results back to input order
457        user_map = {user["id"]: user for user in users}
458        return [user_map.get(user_id) for user_id in user_ids]
459 
460class OrdersByUserLoader(DataLoader):
461    """Batch load orders by user ID."""
462 
463    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
464        """Load orders for multiple users in single query."""
465        orders = await fetch_orders_by_user_ids(user_ids)
466 
467        # Group orders by user_id
468        orders_by_user = {}
469        for order in orders:
470            user_id = order["user_id"]
471            if user_id not in orders_by_user:
472                orders_by_user[user_id] = []
473            orders_by_user[user_id].append(order)
474 
475        # Return in input order
476        return [orders_by_user.get(user_id, []) for user_id in user_ids]
477 
478# Context setup
479def create_context():
480    return {
481        "loaders": {
482            "user": UserLoader(),
483            "orders_by_user": OrdersByUserLoader()
484        }
485    }
486```
487 
488## Best Practices
489 
490### REST APIs
491 
4921. **Consistent Naming**: Use plural nouns for collections (`/users`, not `/user`)
4932. **Stateless**: Each request contains all necessary information
4943. **Use HTTP Status Codes Correctly**: 2xx success, 4xx client errors, 5xx server errors
4954. **Version Your API**: Plan for breaking changes from day one
4965. **Pagination**: Always paginate large collections
4976. **Rate Limiting**: Protect your API with rate limits
4987. **Documentation**: Use OpenAPI/Swagger for interactive docs
499 
500### GraphQL APIs
501 
5021. **Schema First**: Design schema before writing resolvers
5032. **Avoid N+1**: Use DataLoaders for efficient data fetching
5043. **Input Validation**: Validate at schema and resolver levels
5054. **Error Handling**: Return structured errors in mutation payloads
5065. **Pagination**: Use cursor-based pagination (Relay spec)
5076. **Deprecation**: Use `@deprecated` directive for gradual migration
5087. **Monitoring**: Track query complexity and execution time
509 
510## Common Pitfalls
511 
512- **Over-fetching/Under-fetching (REST)**: Fixed in GraphQL but requires DataLoaders
513- **Breaking Changes**: Version APIs or use deprecation strategies
514- **Inconsistent Error Formats**: Standardize error responses
515- **Missing Rate Limits**: APIs without limits are vulnerable to abuse
516- **Poor Documentation**: Undocumented APIs frustrate developers
517- **Ignoring HTTP Semantics**: POST for idempotent operations breaks expectations
518- **Tight Coupling**: API structure shouldn't mirror database schema
519