AgentSkillsCN

api-design

RESTful API设计的最佳实践。在设计端点、请求/响应模式、错误处理，以及API版本控制时使用此功能。

SKILL.md
--- frontmatter
name: api-design
description: RESTful API design best practices. Use when designing endpoints, request/response schemas, error handling, and API versioning.

API Design Skill

RESTful API design principles and patterns for building robust, scalable APIs.

When to Use This Skill

  • •Designing new API endpoints
  • •Defining request/response schemas
  • •Implementing error handling
  • •API versioning strategies
  • •OpenAPI/Swagger documentation

🔗 RESTful Conventions

Resource Naming

code
# ✅ Good: Plural nouns, lowercase, hyphens
GET    /api/v1/users
GET    /api/v1/users/{id}
POST   /api/v1/users
PUT    /api/v1/users/{id}
DELETE /api/v1/users/{id}

GET    /api/v1/api-keys
GET    /api/v1/model-providers

# ❌ Bad: Verbs, camelCase, underscores
GET    /api/v1/getUsers
POST   /api/v1/createUser
GET    /api/v1/api_keys

Nested Resources

code
# User's API keys
GET    /api/v1/users/{userId}/api-keys
POST   /api/v1/users/{userId}/api-keys

# Model's versions
GET    /api/v1/models/{modelId}/versions

HTTP Methods

MethodUsageIdempotent
GETRetrieve resource(s)Yes
POSTCreate resourceNo
PUTReplace resourceYes
PATCHPartial updateYes
DELETERemove resourceYes

📦 Request/Response Format

Successful Response

json
{
  "success": true,
  "data": {
    "id": "user_123",
    "name": "John Doe",
    "email": "john@example.com",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

List Response with Pagination

json
{
  "success": true,
  "data": [
    { "id": "1", "name": "Item 1" },
    { "id": "2", "name": "Item 2" }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "totalPages": 5
  }
}

Error Response

json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      },
      {
        "field": "password",
        "message": "Password must be at least 8 characters"
      }
    ]
  },
  "requestId": "req_abc123"
}

📊 HTTP Status Codes

Success (2xx)

CodeUsage
200 OKGeneral success, GET/PUT/PATCH
201 CreatedResource created (POST)
204 No ContentSuccess with no body (DELETE)

Client Errors (4xx)

CodeUsage
400 Bad RequestInvalid request format/data
401 UnauthorizedMissing/invalid authentication
403 ForbiddenAuthenticated but not authorized
404 Not FoundResource doesn't exist
409 ConflictResource conflict (duplicate)
422 UnprocessableValidation errors
429 Too Many RequestsRate limit exceeded

Server Errors (5xx)

CodeUsage
500 Internal Server ErrorUnexpected server error
502 Bad GatewayUpstream service error
503 Service UnavailableService temporarily down
504 Gateway TimeoutUpstream timeout

🔍 Query Parameters

Filtering

code
GET /api/v1/users?status=active&role=admin
GET /api/v1/models?provider=openai&type=chat

Sorting

code
GET /api/v1/users?sort=createdAt:desc
GET /api/v1/users?sort=name:asc,createdAt:desc

Pagination

code
# Offset-based (simple but slower for large datasets)
GET /api/v1/users?page=2&pageSize=20

# Cursor-based (better for large datasets)
GET /api/v1/users?cursor=eyJpZCI6MTAwfQ&limit=20

Field Selection

code
GET /api/v1/users?fields=id,name,email
GET /api/v1/users?include=profile,settings

Search

code
GET /api/v1/users?q=john
GET /api/v1/users?search=john@example

🔐 Authentication

API Key (Header)

code
GET /api/v1/models
Authorization: Bearer sk-xxxxxxxxxxxxx

API Key (Query - less secure)

code
GET /api/v1/models?api_key=sk-xxxxxxxxxxxxx

JWT Token

code
GET /api/v1/users/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

📋 API Versioning

URL Path (Recommended)

code
/api/v1/users
/api/v2/users

Header

code
GET /api/users
API-Version: 2024-01-15

Query Parameter

code
GET /api/users?version=2

📖 OpenAPI Specification

yaml
openapi: 3.0.3
info:
  title: LLMProxy API
  version: 1.0.0
  description: API for managing LLM proxy services

servers:
  - url: https://api.llmproxy.io/v1

paths:
  /models:
    get:
      summary: List all models
      tags: [Models]
      parameters:
        - name: provider
          in: query
          schema:
            type: string
            enum: [openai, anthropic, azure]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: List of models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    Model:
      type: object
      required: [id, name, provider]
      properties:
        id:
          type: string
          example: "model_123"
        name:
          type: string
          example: "gpt-4"
        provider:
          type: string
          enum: [openai, anthropic, azure]
        
    ModelListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

⚡ Rate Limiting Headers

code
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
Retry-After: 60

📚 References