[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71JSBPNK13E7YVESB0856S2":3,"skill-same:01M71JSBPNK13E7YVESB0856S2":110},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":37,"publishedAt":58,"linkOnly":59,"markdownContent":60,"markdownBody":61,"frontMatter":62,"refName":64,"commitSha":65,"skillDirectory":66,"forksCount":67,"repositoryHtmlUrl":68,"repositoryHomepageUrl":69,"ownerHtmlUrl":70,"ownerBlogUrl":71,"ownerDescription":72,"updatedAt":73,"install":74,"resources":87},"01M71JSBPNK13E7YVESB0856S2","api-design-principles",null,"Use when designing a new REST or GraphQL API, reviewing an API spec before implementation, setting team API standards, or migrating REST to GraphQL. Covers resources, HTTP semantics, pagination, error handling, and pitfalls.","coco-research\u002Fcoco","coco-research","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F68911604?v=4","01M71JRE9C4NM4NSZM4JD0BJTB","Coco Research","01M71JREA0ZMR0PMH3CKA99SN1",631,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fskills\u002Fapi-design-principles\u002FSKILL.md",[18,23,26,29,34],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":30,"categoryName":31,"taxonomyType":32,"taxonomyTypeDesc":33},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":35,"categoryName":36,"taxonomyType":32,"taxonomyTypeDesc":33},"01JBSEEDCAT000000000000032","设计师",[38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"design principles","api","api design principles","principles","api design","design","REST","error handling","api standards","http","use","setting","standards","pitfalls","team","rest to graphql","when","new","resources","error","2026-11-10 10:12:30",false,"---\nname: api-design-principles\ndescription: \"Use when designing a new REST or GraphQL API, reviewing an API spec before implementation, setting team API standards, or migrating REST to GraphQL. Covers resources, HTTP semantics, pagination, error handling, and pitfalls.\"\ndomain: engineering\n---\n\n# API Design Principles\n\nMaster REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.\n\n## When to Use This Skill\n\n- Designing new REST or GraphQL APIs\n- Refactoring existing APIs for better usability\n- Establishing API design standards for your team\n- Reviewing API specifications before implementation\n- Migrating between API paradigms (REST to GraphQL, etc.)\n- Creating developer-friendly API documentation\n- Optimizing APIs for specific use cases (mobile, third-party integrations)\n\n## Core Concepts\n\n### 1. RESTful Design Principles\n\n**Resource-Oriented Architecture**\n\n- Resources are nouns (users, orders, products), not verbs\n- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)\n- URLs represent resource hierarchies\n- Consistent naming conventions\n\n**HTTP Methods Semantics:**\n\n- `GET`: Retrieve resources (idempotent, safe)\n- `POST`: Create new resources\n- `PUT`: Replace entire resource (idempotent)\n- `PATCH`: Partial resource updates\n- `DELETE`: Remove resources (idempotent)\n\n### 2. GraphQL Design Principles\n\n**Schema-First Development**\n\n- Types define your domain model\n- Queries for reading data\n- Mutations for modifying data\n- Subscriptions for real-time updates\n\n**Query Structure:**\n\n- Clients request exactly what they need\n- Single endpoint, multiple operations\n- Strongly typed schema\n- Introspection built-in\n\n### 3. API Versioning Strategies\n\n**URL Versioning:**\n\n```\n\u002Fapi\u002Fv1\u002Fusers\n\u002Fapi\u002Fv2\u002Fusers\n```\n\n**Header Versioning:**\n\n```\nAccept: application\u002Fvnd.api+json; version=1\n```\n\n**Query Parameter Versioning:**\n\n```\n\u002Fapi\u002Fusers?version=1\n```\n\n## REST API Design Patterns\n\n### Pattern 1: Resource Collection Design\n\n```python\n# Good: Resource-oriented endpoints\nGET    \u002Fapi\u002Fusers              # List users (with pagination)\nPOST   \u002Fapi\u002Fusers              # Create user\nGET    \u002Fapi\u002Fusers\u002F{id}         # Get specific user\nPUT    \u002Fapi\u002Fusers\u002F{id}         # Replace user\nPATCH  \u002Fapi\u002Fusers\u002F{id}         # Update user fields\nDELETE \u002Fapi\u002Fusers\u002F{id}         # Delete user\n\n# Nested resources\nGET    \u002Fapi\u002Fusers\u002F{id}\u002Forders  # Get user's orders\nPOST   \u002Fapi\u002Fusers\u002F{id}\u002Forders  # Create order for user\n\n# Bad: Action-oriented endpoints (avoid)\nPOST   \u002Fapi\u002FcreateUser\nPOST   \u002Fapi\u002FgetUserById\nPOST   \u002Fapi\u002FdeleteUser\n```\n\n### Pattern 2: Pagination and Filtering\n\n```python\nfrom typing import List, Optional\nfrom pydantic import BaseModel, Field\n\nclass PaginationParams(BaseModel):\n    page: int = Field(1, ge=1, description=\"Page number\")\n    page_size: int = Field(20, ge=1, le=100, description=\"Items per page\")\n\nclass FilterParams(BaseModel):\n    status: Optional[str] = None\n    created_after: Optional[str] = None\n    search: Optional[str] = None\n\nclass PaginatedResponse(BaseModel):\n    items: List[dict]\n    total: int\n    page: int\n    page_size: int\n    pages: int\n\n    @property\n    def has_next(self) -> bool:\n        return self.page \u003C self.pages\n\n    @property\n    def has_prev(self) -> bool:\n        return self.page > 1\n\n# FastAPI endpoint example\nfrom fastapi import FastAPI, Query, Depends\n\napp = FastAPI()\n\n@app.get(\"\u002Fapi\u002Fusers\", response_model=PaginatedResponse)\nasync def list_users(\n    page: int = Query(1, ge=1),\n    page_size: int = Query(20, ge=1, le=100),\n    status: Optional[str] = Query(None),\n    search: Optional[str] = Query(None)\n):\n    # Apply filters\n    query = build_query(status=status, search=search)\n\n    # Count total\n    total = await count_users(query)\n\n    # Fetch page\n    offset = (page - 1) * page_size\n    users = await fetch_users(query, limit=page_size, offset=offset)\n\n    return PaginatedResponse(\n        items=users,\n        total=total,\n        page=page,\n        page_size=page_size,\n        pages=(total + page_size - 1) \u002F\u002F page_size\n    )\n```\n\n### Pattern 3: Error Handling and Status Codes\n\n```python\nfrom fastapi import HTTPException, status\nfrom pydantic import BaseModel\n\nclass ErrorResponse(BaseModel):\n    error: str\n    message: str\n    details: Optional[dict] = None\n    timestamp: str\n    path: str\n\nclass ValidationErrorDetail(BaseModel):\n    field: str\n    message: str\n    value: Any\n\n# Consistent error responses\nSTATUS_CODES = {\n    \"success\": 200,\n    \"created\": 201,\n    \"no_content\": 204,\n    \"bad_request\": 400,\n    \"unauthorized\": 401,\n    \"forbidden\": 403,\n    \"not_found\": 404,\n    \"conflict\": 409,\n    \"unprocessable\": 422,\n    \"internal_error\": 500\n}\n\ndef raise_not_found(resource: str, id: str):\n    raise HTTPException(\n        status_code=status.HTTP_404_NOT_FOUND,\n        detail={\n            \"error\": \"NotFound\",\n            \"message\": f\"{resource} not found\",\n            \"details\": {\"id\": id}\n        }\n    )\n\ndef raise_validation_error(errors: List[ValidationErrorDetail]):\n    raise HTTPException(\n        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n        detail={\n            \"error\": \"ValidationError\",\n            \"message\": \"Request validation failed\",\n            \"details\": {\"errors\": [e.dict() for e in errors]}\n        }\n    )\n\n# Example usage\n@app.get(\"\u002Fapi\u002Fusers\u002F{user_id}\")\nasync def get_user(user_id: str):\n    user = await fetch_user(user_id)\n    if not user:\n        raise_not_found(\"User\", user_id)\n    return user\n```\n\n### Pattern 4: HATEOAS (Hypermedia as the Engine of Application State)\n\n```python\nclass UserResponse(BaseModel):\n    id: str\n    name: str\n    email: str\n    _links: dict\n\n    @classmethod\n    def from_user(cls, user: User, base_url: str):\n        return cls(\n            id=user.id,\n            name=user.name,\n            email=user.email,\n            _links={\n                \"self\": {\"href\": f\"{base_url}\u002Fapi\u002Fusers\u002F{user.id}\"},\n                \"orders\": {\"href\": f\"{base_url}\u002Fapi\u002Fusers\u002F{user.id}\u002Forders\"},\n                \"update\": {\n                    \"href\": f\"{base_url}\u002Fapi\u002Fusers\u002F{user.id}\",\n                    \"method\": \"PATCH\"\n                },\n                \"delete\": {\n                    \"href\": f\"{base_url}\u002Fapi\u002Fusers\u002F{user.id}\",\n                    \"method\": \"DELETE\"\n                }\n            }\n        )\n```\n**Not for:** HATEOAS-first designs — most teams should stop at Pattern 3.\n\n## GraphQL Design Patterns\n\n### Pattern 1: Schema Design\n\n```graphql\n# schema.graphql\n\n# Clear type definitions\ntype User {\n  id: ID!\n  email: String!\n  name: String!\n  createdAt: DateTime!\n\n  # Relationships\n  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!\n\n  profile: UserProfile\n}\n\ntype Order {\n  id: ID!\n  status: OrderStatus!\n  total: Money!\n  items: [OrderItem!]!\n  createdAt: DateTime!\n\n  # Back-reference\n  user: User!\n}\n\n# Pagination pattern (Relay-style)\ntype OrderConnection {\n  edges: [OrderEdge!]!\n  pageInfo: PageInfo!\n  totalCount: Int!\n}\n\ntype OrderEdge {\n  node: Order!\n  cursor: String!\n}\n\ntype PageInfo {\n  hasNextPage: Boolean!\n  hasPreviousPage: Boolean!\n  startCursor: String\n  endCursor: String\n}\n\n# Enums for type safety\nenum OrderStatus {\n  PENDING\n  CONFIRMED\n  SHIPPED\n  DELIVERED\n  CANCELLED\n}\n\n# Custom scalars\nscalar DateTime\nscalar Money\n\n# Query root\ntype Query {\n  user(id: ID!): User\n  users(first: Int = 20, after: String, search: String): UserConnection!\n\n  order(id: ID!): Order\n}\n\n# Mutation root\ntype Mutation {\n  createUser(input: CreateUserInput!): CreateUserPayload!\n  updateUser(input: UpdateUserInput!): UpdateUserPayload!\n  deleteUser(id: ID!): DeleteUserPayload!\n\n  createOrder(input: CreateOrderInput!): CreateOrderPayload!\n}\n\n# Input types for mutations\ninput CreateUserInput {\n  email: String!\n  name: String!\n  password: String!\n}\n\n# Payload types for mutations\ntype CreateUserPayload {\n  user: User\n  errors: [Error!]\n}\n\ntype Error {\n  field: String\n  message: String!\n}\n```\n\n### Pattern 2: Resolver Design\n\n```python\nfrom typing import Optional, List\nfrom ariadne import QueryType, MutationType, ObjectType\nfrom dataclasses import dataclass\n\nquery = QueryType()\nmutation = MutationType()\nuser_type = ObjectType(\"User\")\n\n@query.field(\"user\")\nasync def resolve_user(obj, info, id: str) -> Optional[dict]:\n    \"\"\"Resolve single user by ID.\"\"\"\n    return await fetch_user_by_id(id)\n\n@query.field(\"users\")\nasync def resolve_users(\n    obj,\n    info,\n    first: int = 20,\n    after: Optional[str] = None,\n    search: Optional[str] = None\n) -> dict:\n    \"\"\"Resolve paginated user list.\"\"\"\n    # Decode cursor\n    offset = decode_cursor(after) if after else 0\n\n    # Fetch users\n    users = await fetch_users(\n        limit=first + 1,  # Fetch one extra to check hasNextPage\n        offset=offset,\n        search=search\n    )\n\n    # Pagination\n    has_next = len(users) > first\n    if has_next:\n        users = users[:first]\n\n    edges = [\n        {\n            \"node\": user,\n            \"cursor\": encode_cursor(offset + i)\n        }\n        for i, user in enumerate(users)\n    ]\n\n    return {\n        \"edges\": edges,\n        \"pageInfo\": {\n            \"hasNextPage\": has_next,\n            \"hasPreviousPage\": offset > 0,\n            \"startCursor\": edges[0][\"cursor\"] if edges else None,\n            \"endCursor\": edges[-1][\"cursor\"] if edges else None\n        },\n        \"totalCount\": await count_users(search=search)\n    }\n\n@user_type.field(\"orders\")\nasync def resolve_user_orders(user: dict, info, first: int = 20) -> dict:\n    \"\"\"Resolve user's orders (N+1 prevention with DataLoader).\"\"\"\n    # Use DataLoader to batch requests\n    loader = info.context[\"loaders\"][\"orders_by_user\"]\n    orders = await loader.load(user[\"id\"])\n\n    return paginate_orders(orders, first)\n\n@mutation.field(\"createUser\")\nasync def resolve_create_user(obj, info, input: dict) -> dict:\n    \"\"\"Create new user.\"\"\"\n    try:\n        # Validate input\n        validate_user_input(input)\n\n        # Create user\n        user = await create_user(\n            email=input[\"email\"],\n            name=input[\"name\"],\n            password=hash_password(input[\"password\"])\n        )\n\n        return {\n            \"user\": user,\n            \"errors\": []\n        }\n    except ValidationError as e:\n        return {\n            \"user\": None,\n            \"errors\": [{\"field\": e.field, \"message\": e.message}]\n        }\n```\n\n### Pattern 3: DataLoader (N+1 Problem Prevention)\n\n```python\nfrom aiodataloader import DataLoader\nfrom typing import List, Optional\n\nclass UserLoader(DataLoader):\n    \"\"\"Batch load users by ID.\"\"\"\n\n    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:\n        \"\"\"Load multiple users in single query.\"\"\"\n        users = await fetch_users_by_ids(user_ids)\n\n        # Map results back to input order\n        user_map = {user[\"id\"]: user for user in users}\n        return [user_map.get(user_id) for user_id in user_ids]\n\nclass OrdersByUserLoader(DataLoader):\n    \"\"\"Batch load orders by user ID.\"\"\"\n\n    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:\n        \"\"\"Load orders for multiple users in single query.\"\"\"\n        orders = await fetch_orders_by_user_ids(user_ids)\n\n        # Group orders by user_id\n        orders_by_user = {}\n        for order in orders:\n            user_id = order[\"user_id\"]\n            if user_id not in orders_by_user:\n                orders_by_user[user_id] = []\n            orders_by_user[user_id].append(order)\n\n        # Return in input order\n        return [orders_by_user.get(user_id, []) for user_id in user_ids]\n\n# Context setup\ndef create_context():\n    return {\n        \"loaders\": {\n            \"user\": UserLoader(),\n            \"orders_by_user\": OrdersByUserLoader()\n        }\n    }\n```\n\n## Best Practices\n\n### REST APIs\n\n1. **Consistent Naming**: Use plural nouns for collections (`\u002Fusers`, not `\u002Fuser`)\n2. **Stateless**: Each request contains all necessary information\n3. **Use HTTP Status Codes Correctly**: 2xx success, 4xx client errors, 5xx server errors\n4. **Version Your API**: Plan for breaking changes from day one\n5. **Pagination**: Always paginate large collections\n6. **Rate Limiting**: Protect your API with rate limits\n7. **Documentation**: Use OpenAPI\u002FSwagger for interactive docs\n\n### GraphQL APIs\n\n1. **Schema First**: Design schema before writing resolvers\n2. **Avoid N+1**: Use DataLoaders for efficient data fetching\n3. **Input Validation**: Validate at schema and resolver levels\n4. **Error Handling**: Return structured errors in mutation payloads\n5. **Pagination**: Use cursor-based pagination (Relay spec)\n6. **Deprecation**: Use `@deprecated` directive for gradual migration\n7. **Monitoring**: Track query complexity and execution time\n\n## Common Pitfalls\n\n- **Over-fetching\u002FUnder-fetching (REST)**: Fixed in GraphQL but requires DataLoaders\n- **Breaking Changes**: Version APIs or use deprecation strategies\n- **Inconsistent Error Formats**: Standardize error responses\n- **Missing Rate Limits**: APIs without limits are vulnerable to abuse\n- **Poor Documentation**: Undocumented APIs frustrate developers\n- **Ignoring HTTP Semantics**: POST for idempotent operations breaks expectations\n- **Tight Coupling**: API structure shouldn't mirror database schema\n\n## Resources\n\n- **references\u002Frest-best-practices.md**: Comprehensive REST API design guide\n- **references\u002Fgraphql-schema-design.md**: GraphQL schema patterns and anti-patterns\n- **assets\u002Frest-api-template.py**: FastAPI REST API template\n- **assets\u002Fapi-design-checklist.md**: Pre-implementation review checklist\n","# API Design Principles\n\nMaster REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.\n\n## When to Use This Skill\n\n- Designing new REST or GraphQL APIs\n- Refactoring existing APIs for better usability\n- Establishing API design standards for your team\n- Reviewing API specifications before implementation\n- Migrating between API paradigms (REST to GraphQL, etc.)\n- Creating developer-friendly API documentation\n- Optimizing APIs for specific use cases (mobile, third-party integrations)\n\n## Core Concepts\n\n### 1. RESTful Design Principles\n\n**Resource-Oriented Architecture**\n\n- Resources are nouns (users, orders, products), not verbs\n- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)\n- URLs represent resource hierarchies\n- Consistent naming conventions\n\n**HTTP Methods Semantics:**\n\n- `GET`: Retrieve resources (idempotent, safe)\n- `POST`: Create new resources\n- `PUT`: Replace entire resource (idempotent)\n- `PATCH`: Partial resource updates\n- `DELETE`: Remove resources (idempotent)\n\n### 2. GraphQL Design Principles\n\n**Schema-First Development**\n\n- Types define your domain model\n- Queries for reading data\n- Mutations for modifying data\n- Subscriptions for real-time updates\n\n**Query Structure:**\n\n- Clients request exactly what they need\n- Single endpoint, multiple operations\n- Strongly typed schema\n- Introspection built-in\n\n### 3. API Versioning Strategies\n\n**URL Versioning:**\n\n```\n\u002Fapi\u002Fv1\u002Fusers\n\u002Fapi\u002Fv2\u002Fusers\n```\n\n**Header Versioning:**\n\n```\nAccept: application\u002Fvnd.api+json; version=1\n```\n\n**Query Parameter Versioning:**\n\n```\n\u002Fapi\u002Fusers?version=1\n```\n\n## REST API Design Patterns\n\n### Pattern 1: Resource Collection Design\n\n```python\n# Good: Resource-oriented endpoints\nGET    \u002Fapi\u002Fusers              # List users (with pagination)\nPOST   \u002Fapi\u002Fusers              # Create user\nGET    \u002Fapi\u002Fusers\u002F{id}         # Get specific user\nPUT    \u002Fapi\u002Fusers\u002F{id}         # Replace user\nPATCH  \u002Fapi\u002Fusers\u002F{id}         # Update user fields\nDELETE \u002Fapi\u002Fusers\u002F{id}         # Delete user\n\n# Nested resources\nGET    \u002Fapi\u002Fusers\u002F{id}\u002Forders  # Get user's orders\nPOST   \u002Fapi\u002Fusers\u002F{id}\u002Forders  # Create order for user\n\n# Bad: Action-oriented endpoints (avoid)\nPOST   \u002Fapi\u002FcreateUser\nPOST   \u002Fapi\u002FgetUserById\nPOST   \u002Fapi\u002FdeleteUser\n```\n\n### Pattern 2: Pagination and Filtering\n\n```python\nfrom typing import List, Optional\nfrom pydantic import BaseModel, Field\n\nclass PaginationParams(BaseModel):\n    page: int = Field(1, ge=1, description=\"Page number\")\n    page_size: int = Field(20, ge=1, le=100, description=\"Items per page\")\n\nclass FilterParams(BaseModel):\n    status: Optional[str] = None\n    created_after: Optional[str] = None\n    search: Optional[str] = None\n\nclass PaginatedResponse(BaseModel):\n    items: List[dict]\n    total: int\n    page: int\n    page_size: int\n    pages: int\n\n    @property\n    def has_next(self) -> bool:\n        return self.page \u003C self.pages\n\n    @property\n    def has_prev(self) -> bool:\n        return self.page > 1\n\n# FastAPI endpoint example\nfrom fastapi import FastAPI, Query, Depends\n\napp = FastAPI()\n\n@app.get(\"\u002Fapi\u002Fusers\", response_model=PaginatedResponse)\nasync def list_users(\n    page: int = Query(1, ge=1),\n    page_size: int = Query(20, ge=1, le=100),\n    status: Optional[str] = Query(None),\n    search: Optional[str] = Query(None)\n):\n    # Apply filters\n    query = build_query(status=status, search=search)\n\n    # Count total\n    total = await count_users(query)\n\n    # Fetch page\n    offset = (page - 1) * page_size\n    users = await fetch_users(query, limit=page_size, offset=offset)\n\n    return PaginatedResponse(\n        items=users,\n        total=total,\n        page=page,\n        page_size=page_size,\n        pages=(total + page_size - 1) \u002F\u002F page_size\n    )\n```\n\n### Pattern 3: Error Handling and Status Codes\n\n```python\nfrom fastapi import HTTPException, status\nfrom pydantic import BaseModel\n\nclass ErrorResponse(BaseModel):\n    error: str\n    message: str\n    details: Optional[dict] = None\n    timestamp: str\n    path: str\n\nclass ValidationErrorDetail(BaseModel):\n    field: str\n    message: str\n    value: Any\n\n# Consistent error responses\nSTATUS_CODES = {\n    \"success\": 200,\n    \"created\": 201,\n    \"no_content\": 204,\n    \"bad_request\": 400,\n    \"unauthorized\": 401,\n    \"forbidden\": 403,\n    \"not_found\": 404,\n    \"conflict\": 409,\n    \"unprocessable\": 422,\n    \"internal_error\": 500\n}\n\ndef raise_not_found(resource: str, id: str):\n    raise HTTPException(\n        status_code=status.HTTP_404_NOT_FOUND,\n        detail={\n            \"error\": \"NotFound\",\n            \"message\": f\"{resource} not found\",\n            \"details\": {\"id\": id}\n        }\n    )\n\ndef raise_validation_error(errors: List[ValidationErrorDetail]):\n    raise HTTPException(\n        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n        detail={\n            \"error\": \"ValidationError\",\n            \"message\": \"Request validation failed\",\n            \"details\": {\"errors\": [e.dict() for e in errors]}\n        }\n    )\n\n# Example usage\n@app.get(\"\u002Fapi\u002Fusers\u002F{user_id}\")\nasync def get_user(user_id: str):\n    user = await fetch_user(user_id)\n    if not user:\n        raise_not_found(\"User\", user_id)\n    return user\n```\n\n### Pattern 4: HATEOAS (Hypermedia as the Engine of Application State)\n\n```python\nclass UserResponse(BaseModel):\n    id: str\n    name: str\n    email: str\n    _links: dict\n\n    @classmethod\n    def from_user(cls, user: User, base_url: str):\n        return cls(\n            id=user.id,\n            name=user.name,\n            email=user.email,\n            _links={\n                \"self\": {\"href\": f\"{base_url}\u002Fapi\u002Fusers\u002F{user.id}\"},\n                \"orders\": {\"href\": f\"{base_url}\u002Fapi\u002Fusers\u002F{user.id}\u002Forders\"},\n                \"update\": {\n                    \"href\": f\"{base_url}\u002Fapi\u002Fusers\u002F{user.id}\",\n                    \"method\": \"PATCH\"\n                },\n                \"delete\": {\n                    \"href\": f\"{base_url}\u002Fapi\u002Fusers\u002F{user.id}\",\n                    \"method\": \"DELETE\"\n                }\n            }\n        )\n```\n**Not for:** HATEOAS-first designs — most teams should stop at Pattern 3.\n\n## GraphQL Design Patterns\n\n### Pattern 1: Schema Design\n\n```graphql\n# schema.graphql\n\n# Clear type definitions\ntype User {\n  id: ID!\n  email: String!\n  name: String!\n  createdAt: DateTime!\n\n  # Relationships\n  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!\n\n  profile: UserProfile\n}\n\ntype Order {\n  id: ID!\n  status: OrderStatus!\n  total: Money!\n  items: [OrderItem!]!\n  createdAt: DateTime!\n\n  # Back-reference\n  user: User!\n}\n\n# Pagination pattern (Relay-style)\ntype OrderConnection {\n  edges: [OrderEdge!]!\n  pageInfo: PageInfo!\n  totalCount: Int!\n}\n\ntype OrderEdge {\n  node: Order!\n  cursor: String!\n}\n\ntype PageInfo {\n  hasNextPage: Boolean!\n  hasPreviousPage: Boolean!\n  startCursor: String\n  endCursor: String\n}\n\n# Enums for type safety\nenum OrderStatus {\n  PENDING\n  CONFIRMED\n  SHIPPED\n  DELIVERED\n  CANCELLED\n}\n\n# Custom scalars\nscalar DateTime\nscalar Money\n\n# Query root\ntype Query {\n  user(id: ID!): User\n  users(first: Int = 20, after: String, search: String): UserConnection!\n\n  order(id: ID!): Order\n}\n\n# Mutation root\ntype Mutation {\n  createUser(input: CreateUserInput!): CreateUserPayload!\n  updateUser(input: UpdateUserInput!): UpdateUserPayload!\n  deleteUser(id: ID!): DeleteUserPayload!\n\n  createOrder(input: CreateOrderInput!): CreateOrderPayload!\n}\n\n# Input types for mutations\ninput CreateUserInput {\n  email: String!\n  name: String!\n  password: String!\n}\n\n# Payload types for mutations\ntype CreateUserPayload {\n  user: User\n  errors: [Error!]\n}\n\ntype Error {\n  field: String\n  message: String!\n}\n```\n\n### Pattern 2: Resolver Design\n\n```python\nfrom typing import Optional, List\nfrom ariadne import QueryType, MutationType, ObjectType\nfrom dataclasses import dataclass\n\nquery = QueryType()\nmutation = MutationType()\nuser_type = ObjectType(\"User\")\n\n@query.field(\"user\")\nasync def resolve_user(obj, info, id: str) -> Optional[dict]:\n    \"\"\"Resolve single user by ID.\"\"\"\n    return await fetch_user_by_id(id)\n\n@query.field(\"users\")\nasync def resolve_users(\n    obj,\n    info,\n    first: int = 20,\n    after: Optional[str] = None,\n    search: Optional[str] = None\n) -> dict:\n    \"\"\"Resolve paginated user list.\"\"\"\n    # Decode cursor\n    offset = decode_cursor(after) if after else 0\n\n    # Fetch users\n    users = await fetch_users(\n        limit=first + 1,  # Fetch one extra to check hasNextPage\n        offset=offset,\n        search=search\n    )\n\n    # Pagination\n    has_next = len(users) > first\n    if has_next:\n        users = users[:first]\n\n    edges = [\n        {\n            \"node\": user,\n            \"cursor\": encode_cursor(offset + i)\n        }\n        for i, user in enumerate(users)\n    ]\n\n    return {\n        \"edges\": edges,\n        \"pageInfo\": {\n            \"hasNextPage\": has_next,\n            \"hasPreviousPage\": offset > 0,\n            \"startCursor\": edges[0][\"cursor\"] if edges else None,\n            \"endCursor\": edges[-1][\"cursor\"] if edges else None\n        },\n        \"totalCount\": await count_users(search=search)\n    }\n\n@user_type.field(\"orders\")\nasync def resolve_user_orders(user: dict, info, first: int = 20) -> dict:\n    \"\"\"Resolve user's orders (N+1 prevention with DataLoader).\"\"\"\n    # Use DataLoader to batch requests\n    loader = info.context[\"loaders\"][\"orders_by_user\"]\n    orders = await loader.load(user[\"id\"])\n\n    return paginate_orders(orders, first)\n\n@mutation.field(\"createUser\")\nasync def resolve_create_user(obj, info, input: dict) -> dict:\n    \"\"\"Create new user.\"\"\"\n    try:\n        # Validate input\n        validate_user_input(input)\n\n        # Create user\n        user = await create_user(\n            email=input[\"email\"],\n            name=input[\"name\"],\n            password=hash_password(input[\"password\"])\n        )\n\n        return {\n            \"user\": user,\n            \"errors\": []\n        }\n    except ValidationError as e:\n        return {\n            \"user\": None,\n            \"errors\": [{\"field\": e.field, \"message\": e.message}]\n        }\n```\n\n### Pattern 3: DataLoader (N+1 Problem Prevention)\n\n```python\nfrom aiodataloader import DataLoader\nfrom typing import List, Optional\n\nclass UserLoader(DataLoader):\n    \"\"\"Batch load users by ID.\"\"\"\n\n    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:\n        \"\"\"Load multiple users in single query.\"\"\"\n        users = await fetch_users_by_ids(user_ids)\n\n        # Map results back to input order\n        user_map = {user[\"id\"]: user for user in users}\n        return [user_map.get(user_id) for user_id in user_ids]\n\nclass OrdersByUserLoader(DataLoader):\n    \"\"\"Batch load orders by user ID.\"\"\"\n\n    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:\n        \"\"\"Load orders for multiple users in single query.\"\"\"\n        orders = await fetch_orders_by_user_ids(user_ids)\n\n        # Group orders by user_id\n        orders_by_user = {}\n        for order in orders:\n            user_id = order[\"user_id\"]\n            if user_id not in orders_by_user:\n                orders_by_user[user_id] = []\n            orders_by_user[user_id].append(order)\n\n        # Return in input order\n        return [orders_by_user.get(user_id, []) for user_id in user_ids]\n\n# Context setup\ndef create_context():\n    return {\n        \"loaders\": {\n            \"user\": UserLoader(),\n            \"orders_by_user\": OrdersByUserLoader()\n        }\n    }\n```\n\n## Best Practices\n\n### REST APIs\n\n1. **Consistent Naming**: Use plural nouns for collections (`\u002Fusers`, not `\u002Fuser`)\n2. **Stateless**: Each request contains all necessary information\n3. **Use HTTP Status Codes Correctly**: 2xx success, 4xx client errors, 5xx server errors\n4. **Version Your API**: Plan for breaking changes from day one\n5. **Pagination**: Always paginate large collections\n6. **Rate Limiting**: Protect your API with rate limits\n7. **Documentation**: Use OpenAPI\u002FSwagger for interactive docs\n\n### GraphQL APIs\n\n1. **Schema First**: Design schema before writing resolvers\n2. **Avoid N+1**: Use DataLoaders for efficient data fetching\n3. **Input Validation**: Validate at schema and resolver levels\n4. **Error Handling**: Return structured errors in mutation payloads\n5. **Pagination**: Use cursor-based pagination (Relay spec)\n6. **Deprecation**: Use `@deprecated` directive for gradual migration\n7. **Monitoring**: Track query complexity and execution time\n\n## Common Pitfalls\n\n- **Over-fetching\u002FUnder-fetching (REST)**: Fixed in GraphQL but requires DataLoaders\n- **Breaking Changes**: Version APIs or use deprecation strategies\n- **Inconsistent Error Formats**: Standardize error responses\n- **Missing Rate Limits**: APIs without limits are vulnerable to abuse\n- **Poor Documentation**: Undocumented APIs frustrate developers\n- **Ignoring HTTP Semantics**: POST for idempotent operations breaks expectations\n- **Tight Coupling**: API structure shouldn't mirror database schema\n\n## Resources\n\n- **references\u002Frest-best-practices.md**: Comprehensive REST API design guide\n- **references\u002Fgraphql-schema-design.md**: GraphQL schema patterns and anti-patterns\n- **assets\u002Frest-api-template.py**: FastAPI REST API template\n- **assets\u002Fapi-design-checklist.md**: Pre-implementation review checklist\n",{"name":5,"domain":63,"description":7},"engineering","main","cd89f013b617f7eea982a9bbc60e992974fda2aa","skills\u002Fapi-design-principles",15,"https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco","https:\u002F\u002Fcocoresearch.org\u002Fcoco\u002F","https:\u002F\u002Fgithub.com\u002Fcoco-research","https:\u002F\u002Fcocoresearch.org","Local-first, open-source tools for people who work with AI agents: governed memory, agents that check their own work, and data that stays on your machine.","2026-11-11 12:18:13",{"source":8,"skillName":5,"commands":75,"prompt":85,"zipAvailable":86},[76,79,82],{"tool":77,"command":78},"npx","npx skills add coco-research\u002Fcoco --skill api-design-principles",{"tool":80,"command":81},"bunx","bunx skills add coco-research\u002Fcoco --skill api-design-principles",{"tool":83,"command":84},"pnpm","pnpm dlx skills add coco-research\u002Fcoco --skill api-design-principles","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fskills\u002Fapi-design-principles\u002FSKILL.md",true,[88,94,100,106],{"path":89,"resourceType":90,"resourceTypeDesc":91,"sizeBytes":92,"sourceHtmlUrl":93},"assets\u002Fapi-design-checklist.md","ASSET","资产文件",3884,"https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fskills\u002Fapi-design-principles\u002Fassets\u002Fapi-design-checklist.md",{"path":95,"resourceType":96,"resourceTypeDesc":97,"sizeBytes":98,"sourceHtmlUrl":99},"assets\u002Frest-api-template.py","SCRIPT","脚本",5323,"https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fskills\u002Fapi-design-principles\u002Fassets\u002Frest-api-template.py",{"path":101,"resourceType":102,"resourceTypeDesc":103,"sizeBytes":104,"sourceHtmlUrl":105},"references\u002Fgraphql-schema-design.md","REFERENCE","参考文档",9005,"https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fskills\u002Fapi-design-principles\u002Freferences\u002Fgraphql-schema-design.md",{"path":107,"resourceType":102,"resourceTypeDesc":103,"sizeBytes":108,"sourceHtmlUrl":109},"references\u002Frest-best-practices.md",7571,"https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fskills\u002Fapi-design-principles\u002Freferences\u002Frest-best-practices.md",[111,135,145,161,191,210],{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":118,"publishedAt":58},"01M71KEJXF9KMT0BWCMRSRFA4M","trading-super-intelligence","Trading Super Intelligence Team. Named real-world personas across 8 cells. Built local-first (LM Studio) and validator-gated. Illustrative composites; see DISCLAIMER.md.","https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fsystems\u002Fsuperintelligence\u002Ftrading\u002FSKILL.md",[117],{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},[119,120,121,122,123,124,125,126,127,52,128,129,130,131,132,133,134],"super","trading super intelligence","intelligence","trading","validator","personas","local","composites","studio","across","world","first","gated","2026","lm studio","local-first",{"skillNo":136,"name":137,"nameZh":6,"description":138,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":139,"categories":140,"keywords":142,"publishedAt":58},"01M71KEFWS3CMAP7DF1P0FWTDE","strategy-super-intelligence","Strategy Super Intelligence Team. Named real-world personas across 7 cells. Built local-first (LM Studio) and validator-gated. Illustrative composites; see DISCLAIMER.md.","https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fsystems\u002Fsuperintelligence\u002Fstrategy\u002FSKILL.md",[141],{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},[143,119,144,121,123,124,125,126,127,52,128,129,130,131,132,133,134],"strategy","strategy super intelligence",{"skillNo":146,"name":147,"nameZh":6,"description":148,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":149,"categories":150,"keywords":155,"publishedAt":58},"01M71KED56ZEPK2QE84QSQPMT0","risk-compliance-super-intelligence","Risk & Compliance (GRC) Super Intelligence Team. Named real-world personas across 7 cells. Built local-first (LM Studio) and validator-gated. Illustrative composites; see DISCLAIMER.md.","https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fsystems\u002Fsuperintelligence\u002Frisk-compliance\u002FSKILL.md",[151,152],{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":153,"categoryName":154,"taxonomyType":32,"taxonomyTypeDesc":33},"01JBSEEDCAT000000000000037","律师与法务",[156,119,157,158,159,121,123,124,125,126,160,127,52,128,129,130,131,132,133,134],"risk","risk compliance super intelligence","compliance","risk compliance","grc",{"skillNo":162,"name":163,"nameZh":6,"description":164,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":165,"categories":166,"keywords":176,"publishedAt":58},"01M71KE9A2FWSC74VA96W1EZSN","product-design-super-intelligence","Your product + design brain trust and decision partner. Named personas across 8 cells spanning product strategy, discovery\u002Fresearch, growth\u002Fmetrics, design foundations\u002Fusability, design leadership\u002Fcraft, UX\u002Fcontent, design systems, and a…","https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fsystems\u002Fsuperintelligence\u002Fproduct-design\u002FSKILL.md",[167,168,171,172,175],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":169,"categoryName":170,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":173,"categoryName":174,"taxonomyType":32,"taxonomyTypeDesc":33},"01JBSEEDCAT000000000000031","产品经理",{"categoryNo":35,"categoryName":36,"taxonomyType":32,"taxonomyTypeDesc":33},[43,177,121,178,119,179,180,181,182,183,184,52,128,185,186,132,187,188,189,190],"product","product design","product design super intelligence","foundations","product-design","decision","design systems","usability","leadership","ux","brain","craft","metrics","trust",{"skillNo":192,"name":193,"nameZh":6,"description":194,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":195,"categories":196,"keywords":199,"publishedAt":58},"01M71KE6H9FPSD9TECYFBPXZ8Y","legal-ip-super-intelligence","Your legal, IP, and regulatory brain trust. 31 named personas across 7 cells covering patent strategy, tech licensing, regulatory litigation, AI governance, open-source compliance, privacy law, and antitrust.","https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fsystems\u002Fsuperintelligence\u002Flegal-ip\u002FSKILL.md",[197,198],{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":153,"categoryName":154,"taxonomyType":32,"taxonomyTypeDesc":33},[200,119,201,121,202,203,190,204,124,205,206,207,143,52,128,208,158,209,132,187],"ip","legal ip super intelligence","legal","sep","tech","litigation","ai governance","open","open-source","governance",{"skillNo":211,"name":212,"nameZh":6,"description":213,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":214,"categories":215,"keywords":217,"publishedAt":58},"01M71KE36QRY610V6YVB9JWRND","healthcare-life-sciences-super-intelligence","Your healthcare and life sciences brain trust. 25 named personas across 7 cells covering drug discovery, medtech, biotech strategy, health policy, genomics, clinical trials, and healthcare economics.","https:\u002F\u002Fgithub.com\u002Fcoco-research\u002Fcoco\u002Fblob\u002Fmain\u002Fsystems\u002Fsuperintelligence\u002Fhealthcare-life-sciences\u002FSKILL.md",[216],{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},[218,119,219,220,121,203,190,221,222,124,223,224,143,52,128,225,226,227,228,132],"healthcare","healthcare life sciences super intelligence","life","economics","discovery","policy","clinical","clinical trials","health","trials","genomics"]