@sylix/coworker 2.0.11 → 2.0.14

package/dist/skills/defaults/backend-development/api-design.md

@@ -0,0 +1,285 @@
+---
+name: api-design
+description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs.
+---
+
+# API Design Principles — CoWorker Edition
+
+Build APIs that developers love to use. These principles apply whether you're building REST or GraphQL.
+
+## When to Use This Skill
+
+- Designing new REST or GraphQL APIs from scratch
+- Refactoring existing APIs for better developer experience
+- Establishing API standards for your team
+- Reviewing API specifications before implementation
+- Creating API documentation
+
+## Core Concepts
+
+### RESTful Design Fundamentals
+
+**Resources are nouns, not verbs:**
+
+```python
+# Good: Resource-oriented
+GET    /api/users              # List users
+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  # User's orders
+
+# Bad: Action-oriented (avoid)
+POST   /api/createUser
+POST   /api/getUserById
+POST   /api/deleteUser
+```
+
+**HTTP Methods Semantics:**
+
+| Method  | Purpose          | Idempotent | Safe |
+|---------|-----------------|------------|------|
+| GET     | Retrieve        | Yes        | Yes  |
+| POST    | Create          | No         | No   |
+| PUT     | Replace         | Yes        | No   |
+| PATCH   | Partial update  | No         | No   |
+| DELETE  | Remove          | Yes        | No   |
+
+### GraphQL Schema Design
+
+```graphql
+# Define types first - this is your contract
+type User {
+  id: ID!
+  email: String!
+  name: String!
+  createdAt: DateTime!
+  
+  # Relationships with pagination
+  orders(first: Int = 20, after: String): OrderConnection!
+}
+
+type Order {
+  id: ID!
+  status: OrderStatus!
+  total: Money!
+  items: [OrderItem!]!
+  user: User!
+}
+
+# Pagination - use cursor-based (Relay spec)
+type OrderConnection {
+  edges: [OrderEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type OrderEdge {
+  node: Order!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+}
+
+enum OrderStatus {
+  PENDING
+  CONFIRMED
+  SHIPPED
+  DELIVERED
+  CANCELLED
+}
+```
+
+### API Versioning Strategies
+
+**URL Versioning (most common):**
+```
+/api/v1/users
+/api/v2/users
+```
+
+**Header Versioning:**
+```
+Accept: application/vnd.api+json; version=1
+```
+
+## REST Patterns
+
+### Pagination Pattern
+
+```python
+from typing import Optional, List
+from pydantic import BaseModel, Field
+
+class PaginationParams(BaseModel):
+    page: int = Field(1, ge=1)
+    page_size: int = Field(20, ge=1, le=100)
+
+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
+
+# FastAPI endpoint
+@app.get("/api/users", response_model=PaginatedResponse)
+async def list_users(
+    page: int = 1,
+    page_size: int = 20,
+    status: Optional[str] = None
+):
+    offset = (page - 1) * page_size
+    users = await fetch_users(limit=page_size, offset=offset, status=status)
+    total = await count_users(status=status)
+    
+    return PaginatedResponse(
+        items=users,
+        total=total,
+        page=page,
+        page_size=page_size,
+        pages=(total + page_size - 1) // page_size
+    )
+```
+
+### Error Handling Pattern
+
+```python
+from fastapi import HTTPException, status
+
+class ErrorResponse(BaseModel):
+    error: str
+    message: str
+    details: Optional[dict] = None
+    timestamp: str
+
+STATUS_CODES = {
+    "success": 200,
+    "created": 201,
+    "bad_request": 400,
+    "unauthorized": 401,
+    "forbidden": 403,
+    "not_found": 404,
+    "conflict": 409,
+    "unprocessable": 422,
+    "internal_error": 500
+}
+
+def not_found(resource: str, id: str):
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail={
+            "error": "NotFound",
+            "message": f"{resource} not found",
+            "details": {"id": id}
+        }
+    )
+```
+
+### HATEOAS (Hypermedia Links)
+
+```python
+class UserResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+    _links: dict
+
+    @classmethod
+    def from_user(cls, 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"}
+            }
+        )
+```
+
+## GraphQL Patterns
+
+### Resolver Pattern with DataLoader
+
+```python
+from ariadne import QueryType
+from aiodataloader import DataLoader
+
+query = QueryType()
+
+class OrdersByUserLoader(DataLoader):
+    """Batch load orders to prevent N+1 queries."""
+    
+    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
+        orders = await fetch_orders_by_user_ids(user_ids)
+        orders_by_user = {}
+        for order in orders:
+            uid = order["user_id"]
+            orders_by_user.setdefault(uid, []).append(order)
+        return [orders_by_user.get(uid, []) for uid in user_ids]
+
+@query.field("users")
+async def resolve_users(obj, info, first: int = 20, after: Optional[str] = None):
+    offset = decode_cursor(after) if after else 0
+    users = await fetch_users(limit=first + 1, offset=offset)
+    
+    has_next = len(users) > first
+    if has_next:
+        users = users[:first]
+    
+    return {
+        "edges": [{"node": u, "cursor": encode_cursor(offset + i)} for i, u in enumerate(users)],
+        "pageInfo": {"hasNextPage": has_next}
+    }
+
+@user_type.field("orders")
+async def resolve_user_orders(user: dict, info, first: int = 20):
+    loader = info.context["loaders"]["orders"]
+    orders = await loader.load(user["id"])
+    return paginate_orders(orders, first)
+```
+
+## Best Practices
+
+### REST
+
+1. **Consistent naming** - Plural nouns (`/users`, not `/user`)
+2. **Stateless** - Each request contains all needed information
+3. **Correct status codes** - 2xx for success, 4xx client errors, 5xx server errors
+4. **Version from day one** - Plan for breaking changes
+5. **Always paginate** - Never return unbounded collections
+6. **Rate limiting** - Protect your API
+7. **OpenAPI/Swagger** - Document interactively
+
+### GraphQL
+
+1. **Schema first** - Design before implementing resolvers
+2. **Prevent N+1** - Use DataLoaders
+3. **Validate inputs** - Schema AND resolver level
+4. **Structured errors** - Return errors in mutation payloads
+5. **Cursor pagination** - Follow Relay spec
+6. **Deprecation** - Use `@deprecated` for gradual migration
+7. **Query complexity** - Monitor and limit
+
+## Common Pitfalls
+
+- Over-fetching/under-fetching in REST (solved by GraphQL with DataLoaders)
+- Breaking changes without versioning
+- Inconsistent error formats
+- Missing rate limits
+- Poor documentation
+- Ignoring HTTP semantics
+- Tight coupling to database schema