[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6D94FSYD72JF91CYFDBZBS0":3,"skill-same:01M6D94FSYD72JF91CYFDBZBS0":83},{"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":34,"publishedAt":48,"linkOnly":49,"markdownContent":50,"markdownBody":51,"frontMatter":52,"refName":54,"commitSha":55,"skillDirectory":56,"forksCount":57,"repositoryHtmlUrl":58,"repositoryHomepageUrl":6,"ownerHtmlUrl":59,"ownerBlogUrl":60,"ownerDescription":61,"updatedAt":62,"install":63,"resources":76},"01M6D94FSYD72JF91CYFDBZBS0","api-design",null,"REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.","oabdelmaksoud\u002FAgention","oabdelmaksoud","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F50699149?v=4","01M6D5CVVN778ZCDP1WHS816SP","Omar Abdelmaksoud","01M6D8A4TE76V3DCSH3D94VG1V",2,"MIT","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention\u002Fblob\u002Fmain\u002Fupstream-archive\u002Fharness\u002F.agents\u002Fskills\u002Fapi-design\u002FSKILL.md",[18,23,26,31],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":32,"categoryName":33,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师",[35,36,37,38,39,40,41,42,43,44,45,46,47],"design","api design","api","status","Production","REST","versioning","filtering","design patterns","pagination","patterns","rate limiting","rest api","2026-11-10 10:12:30",false,"---\nname: api-design\ndescription: REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.\norigin: ECC\n---\n\n# API Design Patterns\n\nConventions and best practices for designing consistent, developer-friendly REST APIs.\n\n## When to Activate\n\n- Designing new API endpoints\n- Reviewing existing API contracts\n- Adding pagination, filtering, or sorting\n- Implementing error handling for APIs\n- Planning API versioning strategy\n- Building public or partner-facing APIs\n\n## Resource Design\n\n### URL Structure\n\n```\n# Resources are nouns, plural, lowercase, kebab-case\nGET    \u002Fapi\u002Fv1\u002Fusers\nGET    \u002Fapi\u002Fv1\u002Fusers\u002F:id\nPOST   \u002Fapi\u002Fv1\u002Fusers\nPUT    \u002Fapi\u002Fv1\u002Fusers\u002F:id\nPATCH  \u002Fapi\u002Fv1\u002Fusers\u002F:id\nDELETE \u002Fapi\u002Fv1\u002Fusers\u002F:id\n\n# Sub-resources for relationships\nGET    \u002Fapi\u002Fv1\u002Fusers\u002F:id\u002Forders\nPOST   \u002Fapi\u002Fv1\u002Fusers\u002F:id\u002Forders\n\n# Actions that don't map to CRUD (use verbs sparingly)\nPOST   \u002Fapi\u002Fv1\u002Forders\u002F:id\u002Fcancel\nPOST   \u002Fapi\u002Fv1\u002Fauth\u002Flogin\nPOST   \u002Fapi\u002Fv1\u002Fauth\u002Frefresh\n```\n\n### Naming Rules\n\n```\n# GOOD\n\u002Fapi\u002Fv1\u002Fteam-members          # kebab-case for multi-word resources\n\u002Fapi\u002Fv1\u002Forders?status=active  # query params for filtering\n\u002Fapi\u002Fv1\u002Fusers\u002F123\u002Forders      # nested resources for ownership\n\n# BAD\n\u002Fapi\u002Fv1\u002FgetUsers              # verb in URL\n\u002Fapi\u002Fv1\u002Fuser                  # singular (use plural)\n\u002Fapi\u002Fv1\u002Fteam_members          # snake_case in URLs\n\u002Fapi\u002Fv1\u002Fusers\u002F123\u002FgetOrders   # verb in nested resource\n```\n\n## HTTP Methods and Status Codes\n\n### Method Semantics\n\n| Method | Idempotent | Safe | Use For |\n|--------|-----------|------|---------|\n| GET | Yes | Yes | Retrieve resources |\n| POST | No | No | Create resources, trigger actions |\n| PUT | Yes | No | Full replacement of a resource |\n| PATCH | No* | No | Partial update of a resource |\n| DELETE | Yes | No | Remove a resource |\n\n*PATCH can be made idempotent with proper implementation\n\n### Status Code Reference\n\n```\n# Success\n200 OK                    — GET, PUT, PATCH (with response body)\n201 Created               — POST (include Location header)\n204 No Content            — DELETE, PUT (no response body)\n\n# Client Errors\n400 Bad Request           — Validation failure, malformed JSON\n401 Unauthorized          — Missing or invalid authentication\n403 Forbidden             — Authenticated but not authorized\n404 Not Found             — Resource doesn't exist\n409 Conflict              — Duplicate entry, state conflict\n422 Unprocessable Entity  — Semantically invalid (valid JSON, bad data)\n429 Too Many Requests     — Rate limit exceeded\n\n# Server Errors\n500 Internal Server Error — Unexpected failure (never expose details)\n502 Bad Gateway           — Upstream service failed\n503 Service Unavailable   — Temporary overload, include Retry-After\n```\n\n### Common Mistakes\n\n```\n# BAD: 200 for everything\n{ \"status\": 200, \"success\": false, \"error\": \"Not found\" }\n\n# GOOD: Use HTTP status codes semantically\nHTTP\u002F1.1 404 Not Found\n{ \"error\": { \"code\": \"not_found\", \"message\": \"User not found\" } }\n\n# BAD: 500 for validation errors\n# GOOD: 400 or 422 with field-level details\n\n# BAD: 200 for created resources\n# GOOD: 201 with Location header\nHTTP\u002F1.1 201 Created\nLocation: \u002Fapi\u002Fv1\u002Fusers\u002Fabc-123\n```\n\n## Response Format\n\n### Success Response\n\n```json\n{\n  \"data\": {\n    \"id\": \"abc-123\",\n    \"email\": \"alice@example.com\",\n    \"name\": \"Alice\",\n    \"created_at\": \"2025-01-15T10:30:00Z\"\n  }\n}\n```\n\n### Collection Response (with Pagination)\n\n```json\n{\n  \"data\": [\n    { \"id\": \"abc-123\", \"name\": \"Alice\" },\n    { \"id\": \"def-456\", \"name\": \"Bob\" }\n  ],\n  \"meta\": {\n    \"total\": 142,\n    \"page\": 1,\n    \"per_page\": 20,\n    \"total_pages\": 8\n  },\n  \"links\": {\n    \"self\": \"\u002Fapi\u002Fv1\u002Fusers?page=1&per_page=20\",\n    \"next\": \"\u002Fapi\u002Fv1\u002Fusers?page=2&per_page=20\",\n    \"last\": \"\u002Fapi\u002Fv1\u002Fusers?page=8&per_page=20\"\n  }\n}\n```\n\n### Error Response\n\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Request validation failed\",\n    \"details\": [\n      {\n        \"field\": \"email\",\n        \"message\": \"Must be a valid email address\",\n        \"code\": \"invalid_format\"\n      },\n      {\n        \"field\": \"age\",\n        \"message\": \"Must be between 0 and 150\",\n        \"code\": \"out_of_range\"\n      }\n    ]\n  }\n}\n```\n\n### Response Envelope Variants\n\n```typescript\n\u002F\u002F Option A: Envelope with data wrapper (recommended for public APIs)\ninterface ApiResponse\u003CT> {\n  data: T;\n  meta?: PaginationMeta;\n  links?: PaginationLinks;\n}\n\ninterface ApiError {\n  error: {\n    code: string;\n    message: string;\n    details?: FieldError[];\n  };\n}\n\n\u002F\u002F Option B: Flat response (simpler, common for internal APIs)\n\u002F\u002F Success: just return the resource directly\n\u002F\u002F Error: return error object\n\u002F\u002F Distinguish by HTTP status code\n```\n\n## Pagination\n\n### Offset-Based (Simple)\n\n```\nGET \u002Fapi\u002Fv1\u002Fusers?page=2&per_page=20\n\n# Implementation\nSELECT * FROM users\nORDER BY created_at DESC\nLIMIT 20 OFFSET 20;\n```\n\n**Pros:** Easy to implement, supports \"jump to page N\"\n**Cons:** Slow on large offsets (OFFSET 100000), inconsistent with concurrent inserts\n\n### Cursor-Based (Scalable)\n\n```\nGET \u002Fapi\u002Fv1\u002Fusers?cursor=eyJpZCI6MTIzfQ&limit=20\n\n# Implementation\nSELECT * FROM users\nWHERE id > :cursor_id\nORDER BY id ASC\nLIMIT 21;  -- fetch one extra to determine has_next\n```\n\n```json\n{\n  \"data\": [...],\n  \"meta\": {\n    \"has_next\": true,\n    \"next_cursor\": \"eyJpZCI6MTQzfQ\"\n  }\n}\n```\n\n**Pros:** Consistent performance regardless of position, stable with concurrent inserts\n**Cons:** Cannot jump to arbitrary page, cursor is opaque\n\n### When to Use Which\n\n| Use Case | Pagination Type |\n|----------|----------------|\n| Admin dashboards, small datasets (\u003C10K) | Offset |\n| Infinite scroll, feeds, large datasets | Cursor |\n| Public APIs | Cursor (default) with offset (optional) |\n| Search results | Offset (users expect page numbers) |\n\n## Filtering, Sorting, and Search\n\n### Filtering\n\n```\n# Simple equality\nGET \u002Fapi\u002Fv1\u002Forders?status=active&customer_id=abc-123\n\n# Comparison operators (use bracket notation)\nGET \u002Fapi\u002Fv1\u002Fproducts?price[gte]=10&price[lte]=100\nGET \u002Fapi\u002Fv1\u002Forders?created_at[after]=2025-01-01\n\n# Multiple values (comma-separated)\nGET \u002Fapi\u002Fv1\u002Fproducts?category=electronics,clothing\n\n# Nested fields (dot notation)\nGET \u002Fapi\u002Fv1\u002Forders?customer.country=US\n```\n\n### Sorting\n\n```\n# Single field (prefix - for descending)\nGET \u002Fapi\u002Fv1\u002Fproducts?sort=-created_at\n\n# Multiple fields (comma-separated)\nGET \u002Fapi\u002Fv1\u002Fproducts?sort=-featured,price,-created_at\n```\n\n### Full-Text Search\n\n```\n# Search query parameter\nGET \u002Fapi\u002Fv1\u002Fproducts?q=wireless+headphones\n\n# Field-specific search\nGET \u002Fapi\u002Fv1\u002Fusers?email=alice\n```\n\n### Sparse Fieldsets\n\n```\n# Return only specified fields (reduces payload)\nGET \u002Fapi\u002Fv1\u002Fusers?fields=id,name,email\nGET \u002Fapi\u002Fv1\u002Forders?fields=id,total,status&include=customer.name\n```\n\n## Authentication and Authorization\n\n### Token-Based Auth\n\n```\n# Bearer token in Authorization header\nGET \u002Fapi\u002Fv1\u002Fusers\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\n\n# API key (for server-to-server)\nGET \u002Fapi\u002Fv1\u002Fdata\nX-API-Key: sk_live_abc123\n```\n\n### Authorization Patterns\n\n```typescript\n\u002F\u002F Resource-level: check ownership\napp.get(\"\u002Fapi\u002Fv1\u002Forders\u002F:id\", async (req, res) => {\n  const order = await Order.findById(req.params.id);\n  if (!order) return res.status(404).json({ error: { code: \"not_found\" } });\n  if (order.userId !== req.user.id) return res.status(403).json({ error: { code: \"forbidden\" } });\n  return res.json({ data: order });\n});\n\n\u002F\u002F Role-based: check permissions\napp.delete(\"\u002Fapi\u002Fv1\u002Fusers\u002F:id\", requireRole(\"admin\"), async (req, res) => {\n  await User.delete(req.params.id);\n  return res.status(204).send();\n});\n```\n\n## Rate Limiting\n\n### Headers\n\n```\nHTTP\u002F1.1 200 OK\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 95\nX-RateLimit-Reset: 1640000000\n\n# When exceeded\nHTTP\u002F1.1 429 Too Many Requests\nRetry-After: 60\n{\n  \"error\": {\n    \"code\": \"rate_limit_exceeded\",\n    \"message\": \"Rate limit exceeded. Try again in 60 seconds.\"\n  }\n}\n```\n\n### Rate Limit Tiers\n\n| Tier | Limit | Window | Use Case |\n|------|-------|--------|----------|\n| Anonymous | 30\u002Fmin | Per IP | Public endpoints |\n| Authenticated | 100\u002Fmin | Per user | Standard API access |\n| Premium | 1000\u002Fmin | Per API key | Paid API plans |\n| Internal | 10000\u002Fmin | Per service | Service-to-service |\n\n## Versioning\n\n### URL Path Versioning (Recommended)\n\n```\n\u002Fapi\u002Fv1\u002Fusers\n\u002Fapi\u002Fv2\u002Fusers\n```\n\n**Pros:** Explicit, easy to route, cacheable\n**Cons:** URL changes between versions\n\n### Header Versioning\n\n```\nGET \u002Fapi\u002Fusers\nAccept: application\u002Fvnd.myapp.v2+json\n```\n\n**Pros:** Clean URLs\n**Cons:** Harder to test, easy to forget\n\n### Versioning Strategy\n\n```\n1. Start with \u002Fapi\u002Fv1\u002F — don't version until you need to\n2. Maintain at most 2 active versions (current + previous)\n3. Deprecation timeline:\n   - Announce deprecation (6 months notice for public APIs)\n   - Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT\n   - Return 410 Gone after sunset date\n4. Non-breaking changes don't need a new version:\n   - Adding new fields to responses\n   - Adding new optional query parameters\n   - Adding new endpoints\n5. Breaking changes require a new version:\n   - Removing or renaming fields\n   - Changing field types\n   - Changing URL structure\n   - Changing authentication method\n```\n\n## Implementation Patterns\n\n### TypeScript (Next.js API Route)\n\n```typescript\nimport { z } from \"zod\";\nimport { NextRequest, NextResponse } from \"next\u002Fserver\";\n\nconst createUserSchema = z.object({\n  email: z.string().email(),\n  name: z.string().min(1).max(100),\n});\n\nexport async function POST(req: NextRequest) {\n  const body = await req.json();\n  const parsed = createUserSchema.safeParse(body);\n\n  if (!parsed.success) {\n    return NextResponse.json({\n      error: {\n        code: \"validation_error\",\n        message: \"Request validation failed\",\n        details: parsed.error.issues.map(i => ({\n          field: i.path.join(\".\"),\n          message: i.message,\n          code: i.code,\n        })),\n      },\n    }, { status: 422 });\n  }\n\n  const user = await createUser(parsed.data);\n\n  return NextResponse.json(\n    { data: user },\n    {\n      status: 201,\n      headers: { Location: `\u002Fapi\u002Fv1\u002Fusers\u002F${user.id}` },\n    },\n  );\n}\n```\n\n### Python (Django REST Framework)\n\n```python\nfrom rest_framework import serializers, viewsets, status\nfrom rest_framework.response import Response\n\nclass CreateUserSerializer(serializers.Serializer):\n    email = serializers.EmailField()\n    name = serializers.CharField(max_length=100)\n\nclass UserSerializer(serializers.ModelSerializer):\n    class Meta:\n        model = User\n        fields = [\"id\", \"email\", \"name\", \"created_at\"]\n\nclass UserViewSet(viewsets.ModelViewSet):\n    serializer_class = UserSerializer\n    permission_classes = [IsAuthenticated]\n\n    def get_serializer_class(self):\n        if self.action == \"create\":\n            return CreateUserSerializer\n        return UserSerializer\n\n    def create(self, request):\n        serializer = CreateUserSerializer(data=request.data)\n        serializer.is_valid(raise_exception=True)\n        user = UserService.create(**serializer.validated_data)\n        return Response(\n            {\"data\": UserSerializer(user).data},\n            status=status.HTTP_201_CREATED,\n            headers={\"Location\": f\"\u002Fapi\u002Fv1\u002Fusers\u002F{user.id}\"},\n        )\n```\n\n### Go (net\u002Fhttp)\n\n```go\nfunc (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {\n    var req CreateUserRequest\n    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {\n        writeError(w, http.StatusBadRequest, \"invalid_json\", \"Invalid request body\")\n        return\n    }\n\n    if err := req.Validate(); err != nil {\n        writeError(w, http.StatusUnprocessableEntity, \"validation_error\", err.Error())\n        return\n    }\n\n    user, err := h.service.Create(r.Context(), req)\n    if err != nil {\n        switch {\n        case errors.Is(err, domain.ErrEmailTaken):\n            writeError(w, http.StatusConflict, \"email_taken\", \"Email already registered\")\n        default:\n            writeError(w, http.StatusInternalServerError, \"internal_error\", \"Internal error\")\n        }\n        return\n    }\n\n    w.Header().Set(\"Location\", fmt.Sprintf(\"\u002Fapi\u002Fv1\u002Fusers\u002F%s\", user.ID))\n    writeJSON(w, http.StatusCreated, map[string]any{\"data\": user})\n}\n```\n\n## API Design Checklist\n\nBefore shipping a new endpoint:\n\n- [ ] Resource URL follows naming conventions (plural, kebab-case, no verbs)\n- [ ] Correct HTTP method used (GET for reads, POST for creates, etc.)\n- [ ] Appropriate status codes returned (not 200 for everything)\n- [ ] Input validated with schema (Zod, Pydantic, Bean Validation)\n- [ ] Error responses follow standard format with codes and messages\n- [ ] Pagination implemented for list endpoints (cursor or offset)\n- [ ] Authentication required (or explicitly marked as public)\n- [ ] Authorization checked (user can only access their own resources)\n- [ ] Rate limiting configured\n- [ ] Response does not leak internal details (stack traces, SQL errors)\n- [ ] Consistent naming with existing endpoints (camelCase vs snake_case)\n- [ ] Documented (OpenAPI\u002FSwagger spec updated)\n","# API Design Patterns\n\nConventions and best practices for designing consistent, developer-friendly REST APIs.\n\n## When to Activate\n\n- Designing new API endpoints\n- Reviewing existing API contracts\n- Adding pagination, filtering, or sorting\n- Implementing error handling for APIs\n- Planning API versioning strategy\n- Building public or partner-facing APIs\n\n## Resource Design\n\n### URL Structure\n\n```\n# Resources are nouns, plural, lowercase, kebab-case\nGET    \u002Fapi\u002Fv1\u002Fusers\nGET    \u002Fapi\u002Fv1\u002Fusers\u002F:id\nPOST   \u002Fapi\u002Fv1\u002Fusers\nPUT    \u002Fapi\u002Fv1\u002Fusers\u002F:id\nPATCH  \u002Fapi\u002Fv1\u002Fusers\u002F:id\nDELETE \u002Fapi\u002Fv1\u002Fusers\u002F:id\n\n# Sub-resources for relationships\nGET    \u002Fapi\u002Fv1\u002Fusers\u002F:id\u002Forders\nPOST   \u002Fapi\u002Fv1\u002Fusers\u002F:id\u002Forders\n\n# Actions that don't map to CRUD (use verbs sparingly)\nPOST   \u002Fapi\u002Fv1\u002Forders\u002F:id\u002Fcancel\nPOST   \u002Fapi\u002Fv1\u002Fauth\u002Flogin\nPOST   \u002Fapi\u002Fv1\u002Fauth\u002Frefresh\n```\n\n### Naming Rules\n\n```\n# GOOD\n\u002Fapi\u002Fv1\u002Fteam-members          # kebab-case for multi-word resources\n\u002Fapi\u002Fv1\u002Forders?status=active  # query params for filtering\n\u002Fapi\u002Fv1\u002Fusers\u002F123\u002Forders      # nested resources for ownership\n\n# BAD\n\u002Fapi\u002Fv1\u002FgetUsers              # verb in URL\n\u002Fapi\u002Fv1\u002Fuser                  # singular (use plural)\n\u002Fapi\u002Fv1\u002Fteam_members          # snake_case in URLs\n\u002Fapi\u002Fv1\u002Fusers\u002F123\u002FgetOrders   # verb in nested resource\n```\n\n## HTTP Methods and Status Codes\n\n### Method Semantics\n\n| Method | Idempotent | Safe | Use For |\n|--------|-----------|------|---------|\n| GET | Yes | Yes | Retrieve resources |\n| POST | No | No | Create resources, trigger actions |\n| PUT | Yes | No | Full replacement of a resource |\n| PATCH | No* | No | Partial update of a resource |\n| DELETE | Yes | No | Remove a resource |\n\n*PATCH can be made idempotent with proper implementation\n\n### Status Code Reference\n\n```\n# Success\n200 OK                    — GET, PUT, PATCH (with response body)\n201 Created               — POST (include Location header)\n204 No Content            — DELETE, PUT (no response body)\n\n# Client Errors\n400 Bad Request           — Validation failure, malformed JSON\n401 Unauthorized          — Missing or invalid authentication\n403 Forbidden             — Authenticated but not authorized\n404 Not Found             — Resource doesn't exist\n409 Conflict              — Duplicate entry, state conflict\n422 Unprocessable Entity  — Semantically invalid (valid JSON, bad data)\n429 Too Many Requests     — Rate limit exceeded\n\n# Server Errors\n500 Internal Server Error — Unexpected failure (never expose details)\n502 Bad Gateway           — Upstream service failed\n503 Service Unavailable   — Temporary overload, include Retry-After\n```\n\n### Common Mistakes\n\n```\n# BAD: 200 for everything\n{ \"status\": 200, \"success\": false, \"error\": \"Not found\" }\n\n# GOOD: Use HTTP status codes semantically\nHTTP\u002F1.1 404 Not Found\n{ \"error\": { \"code\": \"not_found\", \"message\": \"User not found\" } }\n\n# BAD: 500 for validation errors\n# GOOD: 400 or 422 with field-level details\n\n# BAD: 200 for created resources\n# GOOD: 201 with Location header\nHTTP\u002F1.1 201 Created\nLocation: \u002Fapi\u002Fv1\u002Fusers\u002Fabc-123\n```\n\n## Response Format\n\n### Success Response\n\n```json\n{\n  \"data\": {\n    \"id\": \"abc-123\",\n    \"email\": \"alice@example.com\",\n    \"name\": \"Alice\",\n    \"created_at\": \"2025-01-15T10:30:00Z\"\n  }\n}\n```\n\n### Collection Response (with Pagination)\n\n```json\n{\n  \"data\": [\n    { \"id\": \"abc-123\", \"name\": \"Alice\" },\n    { \"id\": \"def-456\", \"name\": \"Bob\" }\n  ],\n  \"meta\": {\n    \"total\": 142,\n    \"page\": 1,\n    \"per_page\": 20,\n    \"total_pages\": 8\n  },\n  \"links\": {\n    \"self\": \"\u002Fapi\u002Fv1\u002Fusers?page=1&per_page=20\",\n    \"next\": \"\u002Fapi\u002Fv1\u002Fusers?page=2&per_page=20\",\n    \"last\": \"\u002Fapi\u002Fv1\u002Fusers?page=8&per_page=20\"\n  }\n}\n```\n\n### Error Response\n\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Request validation failed\",\n    \"details\": [\n      {\n        \"field\": \"email\",\n        \"message\": \"Must be a valid email address\",\n        \"code\": \"invalid_format\"\n      },\n      {\n        \"field\": \"age\",\n        \"message\": \"Must be between 0 and 150\",\n        \"code\": \"out_of_range\"\n      }\n    ]\n  }\n}\n```\n\n### Response Envelope Variants\n\n```typescript\n\u002F\u002F Option A: Envelope with data wrapper (recommended for public APIs)\ninterface ApiResponse\u003CT> {\n  data: T;\n  meta?: PaginationMeta;\n  links?: PaginationLinks;\n}\n\ninterface ApiError {\n  error: {\n    code: string;\n    message: string;\n    details?: FieldError[];\n  };\n}\n\n\u002F\u002F Option B: Flat response (simpler, common for internal APIs)\n\u002F\u002F Success: just return the resource directly\n\u002F\u002F Error: return error object\n\u002F\u002F Distinguish by HTTP status code\n```\n\n## Pagination\n\n### Offset-Based (Simple)\n\n```\nGET \u002Fapi\u002Fv1\u002Fusers?page=2&per_page=20\n\n# Implementation\nSELECT * FROM users\nORDER BY created_at DESC\nLIMIT 20 OFFSET 20;\n```\n\n**Pros:** Easy to implement, supports \"jump to page N\"\n**Cons:** Slow on large offsets (OFFSET 100000), inconsistent with concurrent inserts\n\n### Cursor-Based (Scalable)\n\n```\nGET \u002Fapi\u002Fv1\u002Fusers?cursor=eyJpZCI6MTIzfQ&limit=20\n\n# Implementation\nSELECT * FROM users\nWHERE id > :cursor_id\nORDER BY id ASC\nLIMIT 21;  -- fetch one extra to determine has_next\n```\n\n```json\n{\n  \"data\": [...],\n  \"meta\": {\n    \"has_next\": true,\n    \"next_cursor\": \"eyJpZCI6MTQzfQ\"\n  }\n}\n```\n\n**Pros:** Consistent performance regardless of position, stable with concurrent inserts\n**Cons:** Cannot jump to arbitrary page, cursor is opaque\n\n### When to Use Which\n\n| Use Case | Pagination Type |\n|----------|----------------|\n| Admin dashboards, small datasets (\u003C10K) | Offset |\n| Infinite scroll, feeds, large datasets | Cursor |\n| Public APIs | Cursor (default) with offset (optional) |\n| Search results | Offset (users expect page numbers) |\n\n## Filtering, Sorting, and Search\n\n### Filtering\n\n```\n# Simple equality\nGET \u002Fapi\u002Fv1\u002Forders?status=active&customer_id=abc-123\n\n# Comparison operators (use bracket notation)\nGET \u002Fapi\u002Fv1\u002Fproducts?price[gte]=10&price[lte]=100\nGET \u002Fapi\u002Fv1\u002Forders?created_at[after]=2025-01-01\n\n# Multiple values (comma-separated)\nGET \u002Fapi\u002Fv1\u002Fproducts?category=electronics,clothing\n\n# Nested fields (dot notation)\nGET \u002Fapi\u002Fv1\u002Forders?customer.country=US\n```\n\n### Sorting\n\n```\n# Single field (prefix - for descending)\nGET \u002Fapi\u002Fv1\u002Fproducts?sort=-created_at\n\n# Multiple fields (comma-separated)\nGET \u002Fapi\u002Fv1\u002Fproducts?sort=-featured,price,-created_at\n```\n\n### Full-Text Search\n\n```\n# Search query parameter\nGET \u002Fapi\u002Fv1\u002Fproducts?q=wireless+headphones\n\n# Field-specific search\nGET \u002Fapi\u002Fv1\u002Fusers?email=alice\n```\n\n### Sparse Fieldsets\n\n```\n# Return only specified fields (reduces payload)\nGET \u002Fapi\u002Fv1\u002Fusers?fields=id,name,email\nGET \u002Fapi\u002Fv1\u002Forders?fields=id,total,status&include=customer.name\n```\n\n## Authentication and Authorization\n\n### Token-Based Auth\n\n```\n# Bearer token in Authorization header\nGET \u002Fapi\u002Fv1\u002Fusers\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\n\n# API key (for server-to-server)\nGET \u002Fapi\u002Fv1\u002Fdata\nX-API-Key: sk_live_abc123\n```\n\n### Authorization Patterns\n\n```typescript\n\u002F\u002F Resource-level: check ownership\napp.get(\"\u002Fapi\u002Fv1\u002Forders\u002F:id\", async (req, res) => {\n  const order = await Order.findById(req.params.id);\n  if (!order) return res.status(404).json({ error: { code: \"not_found\" } });\n  if (order.userId !== req.user.id) return res.status(403).json({ error: { code: \"forbidden\" } });\n  return res.json({ data: order });\n});\n\n\u002F\u002F Role-based: check permissions\napp.delete(\"\u002Fapi\u002Fv1\u002Fusers\u002F:id\", requireRole(\"admin\"), async (req, res) => {\n  await User.delete(req.params.id);\n  return res.status(204).send();\n});\n```\n\n## Rate Limiting\n\n### Headers\n\n```\nHTTP\u002F1.1 200 OK\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 95\nX-RateLimit-Reset: 1640000000\n\n# When exceeded\nHTTP\u002F1.1 429 Too Many Requests\nRetry-After: 60\n{\n  \"error\": {\n    \"code\": \"rate_limit_exceeded\",\n    \"message\": \"Rate limit exceeded. Try again in 60 seconds.\"\n  }\n}\n```\n\n### Rate Limit Tiers\n\n| Tier | Limit | Window | Use Case |\n|------|-------|--------|----------|\n| Anonymous | 30\u002Fmin | Per IP | Public endpoints |\n| Authenticated | 100\u002Fmin | Per user | Standard API access |\n| Premium | 1000\u002Fmin | Per API key | Paid API plans |\n| Internal | 10000\u002Fmin | Per service | Service-to-service |\n\n## Versioning\n\n### URL Path Versioning (Recommended)\n\n```\n\u002Fapi\u002Fv1\u002Fusers\n\u002Fapi\u002Fv2\u002Fusers\n```\n\n**Pros:** Explicit, easy to route, cacheable\n**Cons:** URL changes between versions\n\n### Header Versioning\n\n```\nGET \u002Fapi\u002Fusers\nAccept: application\u002Fvnd.myapp.v2+json\n```\n\n**Pros:** Clean URLs\n**Cons:** Harder to test, easy to forget\n\n### Versioning Strategy\n\n```\n1. Start with \u002Fapi\u002Fv1\u002F — don't version until you need to\n2. Maintain at most 2 active versions (current + previous)\n3. Deprecation timeline:\n   - Announce deprecation (6 months notice for public APIs)\n   - Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT\n   - Return 410 Gone after sunset date\n4. Non-breaking changes don't need a new version:\n   - Adding new fields to responses\n   - Adding new optional query parameters\n   - Adding new endpoints\n5. Breaking changes require a new version:\n   - Removing or renaming fields\n   - Changing field types\n   - Changing URL structure\n   - Changing authentication method\n```\n\n## Implementation Patterns\n\n### TypeScript (Next.js API Route)\n\n```typescript\nimport { z } from \"zod\";\nimport { NextRequest, NextResponse } from \"next\u002Fserver\";\n\nconst createUserSchema = z.object({\n  email: z.string().email(),\n  name: z.string().min(1).max(100),\n});\n\nexport async function POST(req: NextRequest) {\n  const body = await req.json();\n  const parsed = createUserSchema.safeParse(body);\n\n  if (!parsed.success) {\n    return NextResponse.json({\n      error: {\n        code: \"validation_error\",\n        message: \"Request validation failed\",\n        details: parsed.error.issues.map(i => ({\n          field: i.path.join(\".\"),\n          message: i.message,\n          code: i.code,\n        })),\n      },\n    }, { status: 422 });\n  }\n\n  const user = await createUser(parsed.data);\n\n  return NextResponse.json(\n    { data: user },\n    {\n      status: 201,\n      headers: { Location: `\u002Fapi\u002Fv1\u002Fusers\u002F${user.id}` },\n    },\n  );\n}\n```\n\n### Python (Django REST Framework)\n\n```python\nfrom rest_framework import serializers, viewsets, status\nfrom rest_framework.response import Response\n\nclass CreateUserSerializer(serializers.Serializer):\n    email = serializers.EmailField()\n    name = serializers.CharField(max_length=100)\n\nclass UserSerializer(serializers.ModelSerializer):\n    class Meta:\n        model = User\n        fields = [\"id\", \"email\", \"name\", \"created_at\"]\n\nclass UserViewSet(viewsets.ModelViewSet):\n    serializer_class = UserSerializer\n    permission_classes = [IsAuthenticated]\n\n    def get_serializer_class(self):\n        if self.action == \"create\":\n            return CreateUserSerializer\n        return UserSerializer\n\n    def create(self, request):\n        serializer = CreateUserSerializer(data=request.data)\n        serializer.is_valid(raise_exception=True)\n        user = UserService.create(**serializer.validated_data)\n        return Response(\n            {\"data\": UserSerializer(user).data},\n            status=status.HTTP_201_CREATED,\n            headers={\"Location\": f\"\u002Fapi\u002Fv1\u002Fusers\u002F{user.id}\"},\n        )\n```\n\n### Go (net\u002Fhttp)\n\n```go\nfunc (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {\n    var req CreateUserRequest\n    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {\n        writeError(w, http.StatusBadRequest, \"invalid_json\", \"Invalid request body\")\n        return\n    }\n\n    if err := req.Validate(); err != nil {\n        writeError(w, http.StatusUnprocessableEntity, \"validation_error\", err.Error())\n        return\n    }\n\n    user, err := h.service.Create(r.Context(), req)\n    if err != nil {\n        switch {\n        case errors.Is(err, domain.ErrEmailTaken):\n            writeError(w, http.StatusConflict, \"email_taken\", \"Email already registered\")\n        default:\n            writeError(w, http.StatusInternalServerError, \"internal_error\", \"Internal error\")\n        }\n        return\n    }\n\n    w.Header().Set(\"Location\", fmt.Sprintf(\"\u002Fapi\u002Fv1\u002Fusers\u002F%s\", user.ID))\n    writeJSON(w, http.StatusCreated, map[string]any{\"data\": user})\n}\n```\n\n## API Design Checklist\n\nBefore shipping a new endpoint:\n\n- [ ] Resource URL follows naming conventions (plural, kebab-case, no verbs)\n- [ ] Correct HTTP method used (GET for reads, POST for creates, etc.)\n- [ ] Appropriate status codes returned (not 200 for everything)\n- [ ] Input validated with schema (Zod, Pydantic, Bean Validation)\n- [ ] Error responses follow standard format with codes and messages\n- [ ] Pagination implemented for list endpoints (cursor or offset)\n- [ ] Authentication required (or explicitly marked as public)\n- [ ] Authorization checked (user can only access their own resources)\n- [ ] Rate limiting configured\n- [ ] Response does not leak internal details (stack traces, SQL errors)\n- [ ] Consistent naming with existing endpoints (camelCase vs snake_case)\n- [ ] Documented (OpenAPI\u002FSwagger spec updated)\n",{"name":5,"origin":53,"description":7},"ECC","main","a318f48de3c5718e8ea2e9f6fae7790e8a759e85","upstream-archive\u002Fharness\u002F.agents\u002Fskills\u002Fapi-design",0,"https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud","https:\u002F\u002Fwww.linkedin.com\u002Fin\u002Fo-abdelmaksoud\u002F","Full-Stack Engineer | AI Systems Architect | Building autonomous multi-agent systems","2026-03-08 21:23:03",{"source":8,"skillName":5,"commands":64,"prompt":74,"zipAvailable":75},[65,68,71],{"tool":66,"command":67},"npx","npx skills add oabdelmaksoud\u002FAgention --skill api-design",{"tool":69,"command":70},"bunx","bunx skills add oabdelmaksoud\u002FAgention --skill api-design",{"tool":72,"command":73},"pnpm","pnpm dlx skills add oabdelmaksoud\u002FAgention --skill api-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention\u002Fblob\u002Fmain\u002Fupstream-archive\u002Fharness\u002F.agents\u002Fskills\u002Fapi-design\u002FSKILL.md",true,[77],{"path":78,"resourceType":79,"resourceTypeDesc":80,"sizeBytes":81,"sourceHtmlUrl":82},"agents\u002Fopenai.yaml","REFERENCE","参考文档",247,"https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention\u002Fblob\u002Fmain\u002Fupstream-archive\u002Fharness\u002F.agents\u002Fskills\u002Fapi-design\u002Fagents\u002Fopenai.yaml",[84,106,120,149,174,194],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":93,"publishedAt":48},"01M6G2QFCBNBYAJF2KTK85G9A6","visa-doc-translate","Translate visa application documents (images) to English and create a bilingual PDF with original and translation","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fvisa-doc-translate\u002FSKILL.md",[90],{"categoryNo":91,"categoryName":92,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000002","文档处理",[94,95,96,97,98,99,100,101,102,103,104,105],"translate","doc","visa doc translate","bilingual","with","english","application","PDF","translation","documents","create","images",{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":112,"publishedAt":48},"01M6G2QB09TSK6BY4ME5X20EVQ","verification-loop","A comprehensive verification system for Claude Code sessions.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fverification-loop\u002FSKILL.md",[],[113,114,115,116,117,118,119],"verification","loop","verification loop","sessions","code","claude code sessions","system",{"skillNo":121,"name":122,"nameZh":6,"description":123,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":124,"categories":125,"keywords":133,"publishedAt":48},"01M6G2Q6V2F7G03VAAF27FXPJR","tdd-workflow","Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Ftdd-workflow\u002FSKILL.md",[126,129,132],{"categoryNo":127,"categoryName":128,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":130,"categoryName":131,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},[134,135,136,137,138,139,140,141,142,117,143,144,145,146,98,147,148],"workflow","tdd","tdd workflow","use","unit","coverage","refactoring","e2e","integration","development","e2e tests","tests","driven","test","writing",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":155,"publishedAt":48},"01M6G2Q359YJRWAR2PFCEQAXF3","swiftui-patterns","SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS\u002FmacOS UI best practices.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fswiftui-patterns\u002FSKILL.md",[],[45,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,98],"swiftui","swiftui patterns","architecture","macos","performance","state management","best practices","state","ui","Optimization","ios","architecture patterns","Composition","performance optimization","view","management","swiftui architecture","navigation",{"skillNo":175,"name":176,"nameZh":6,"description":177,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":178,"categories":179,"keywords":181,"publishedAt":48},"01M6G2PY8B2FWZTWPZ84H83Y7C","swift-protocol-di-testing","Protocol-based dependency injection for testable Swift code — mock file system, network, and external APIs using focused protocols and Swift Testing.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fswift-protocol-di-testing\u002FSKILL.md",[180],{"categoryNo":127,"categoryName":128,"taxonomyType":21,"taxonomyTypeDesc":22},[182,183,184,185,117,186,187,188,189,119,190,191,192,193],"swift protocol di testing","protocol","swift","testing","protocols","file","network","injection","dependency","swift testing","dependency injection","mock",{"skillNo":195,"name":196,"nameZh":6,"description":197,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":198,"categories":199,"keywords":200,"publishedAt":48},"01M6G2PSCN2GXV9FFZDRRRWVB6","swift-concurrency-6-2","Swift 6.2 Approachable Concurrency — single-threaded by default, @concurrent for explicit background offloading, isolated conformances for main actor types.","https:\u002F\u002Fgithub.com\u002Foabdelmaksoud\u002FAgention\u002Fblob\u002Fmain\u002Fupstream-sync\u002Fwork\u002Fecc\u002Fskills\u002Fswift-concurrency-6-2\u002FSKILL.md",[],[201,202,203,184,204,54,205],"concurrency","swift concurrency","swift concurrency 6 2","default","types"]