---
id: sm-api-design
name: "api-design"
url: https://skills.yangsir.net/skill/sm-api-design
author: supercent-io
domain: ai-backend-engineering
tags: ["restful-api", "graphql", "microservices", "api-gateway", "hateoas"]
install_count: 11500
rating: 4.50 (460 reviews)
github: https://github.com/supercent-io/skills-template
---

# api-design

> 此技能用于设计新的REST API、GraphQL模式、重构API端点、编写API规范、制定API版本策略及定义数据模型，确保API设计合理。

**Stats**: 11,500 installs · 4.5/5 (460 reviews)

## Before / After 对比

### 精心规划与设计REST API和GraphQL模式，构建高效、易用且具备良好扩展性的后端接口体系

## Readme

# api-design

# API Design

## When to use this skill

- Designing new REST APIs

- Creating GraphQL schemas

- Refactoring API endpoints

- Documenting API specifications

- API versioning strategies

- Defining data models and relationships

## Instructions

### Step 1: Define API requirements

- Identify resources and entities

- Define relationships between entities

- Specify operations (CRUD, custom actions)

- Plan authentication/authorization

- Consider pagination, filtering, sorting

### Step 2: Design REST API

**Resource naming**:

- Use nouns, not verbs: `/users` not `/getUsers`

- Use plural names: `/users/{id}`

- Nest resources logically: `/users/{id}/posts`

- Keep URLs short and intuitive

**HTTP methods**:

- `GET`: Retrieve resources (idempotent)

- `POST`: Create new resources

- `PUT`: Replace entire resource

- `PATCH`: Partial update

- `DELETE`: Remove resources (idempotent)

**Response codes**:

- `200 OK`: Success with response body

- `201 Created`: Resource created successfully

- `204 No Content`: Success with no response body

- `400 Bad Request`: Invalid input

- `401 Unauthorized`: Authentication required

- `403 Forbidden`: No permission

- `404 Not Found`: Resource doesn't exist

- `409 Conflict`: Resource conflict

- `422 Unprocessable Entity`: Validation failed

- `500 Internal Server Error`: Server error

**Example REST endpoint**:

```
GET    /api/v1/users           # List users
GET    /api/v1/users/{id}      # Get user
POST   /api/v1/users           # Create user
PUT    /api/v1/users/{id}      # Update user
PATCH  /api/v1/users/{id}      # Partial update
DELETE /api/v1/users/{id}      # Delete user

```

### Step 3: Request/Response format

**Request example**:

```
POST /api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin"
}

```

**Response example**:

```
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/123

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

```

### Step 4: Error handling

**Error response format**:

```
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input provided",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

```

### Step 5: Pagination

**Query parameters**:

```
GET /api/v1/users?page=2&limit=20&sort=-created_at&filter=role:admin

```

**Response with pagination**:

```
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 100,
    "pages": 5
  },
  "links": {
    "self": "/api/v1/users?page=2&limit=20",
    "first": "/api/v1/users?page=1&limit=20",
    "prev": "/api/v1/users?page=1&limit=20",
    "next": "/api/v1/users?page=3&limit=20",
    "last": "/api/v1/users?page=5&limit=20"
  }
}

```

### Step 6: Authentication

**Options**:

- JWT (JSON Web Tokens)

- OAuth 2.0

- API Keys

- Session-based

**Example with JWT**:

```
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

```

### Step 7: Versioning

**URL versioning** (recommended):

```
/api/v1/users
/api/v2/users

```

**Header versioning**:

```
GET /api/users
Accept: application/vnd.api+json; version=1

```

### Step 8: Documentation

Create OpenAPI 3.0 specification:

```
openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
    UserCreate:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email

```

## Best practices

- **Consistency**: Use consistent naming, structure, and patterns

- **Versioning**: Always version your APIs from the start

- **Security**: Implement authentication and authorization

- **Validation**: Validate all inputs on the server side

- **Rate limiting**: Protect against abuse

- **Caching**: Use ETags and Cache-Control headers

- **CORS**: Configure properly for web clients

- **Documentation**: Keep docs up-to-date with code

- **Testing**: Test all endpoints thoroughly

- **Monitoring**: Log requests and track performance

## Common patterns

**Filtering**:

```
GET /api/v1/users?role=admin&status=active

```

**Sorting**:

```
GET /api/v1/users?sort=-created_at,name

```

**Field selection**:

```
GET /api/v1/users?fields=id,name,email

```

**Batch operations**:

```
POST /api/v1/users/batch
{
  "operations": [
    {"action": "create", "data": {...}},
    {"action": "update", "id": 123, "data": {...}}
  ]
}

```

## GraphQL alternative

If REST doesn't fit, consider GraphQL:

```
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
  createdAt: DateTime!
}

type Query {
  users(page: Int, limit: Int): [User!]!
  user(id: ID!): User
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}

```

## References

- [OpenAPI Specification](https://swagger.io/specification/)

- [REST API Tutorial](https://restfulapi.net/)

- [GraphQL Best Practices](https://graphql.org/learn/best-practices/)

- [HTTP Status Codes](https://httpstatuses.com/)

## Examples

### Example 1: Basic usage

### Example 2: Advanced usage
Weekly Installs11.2KRepository[supercent-io/sk…template](https://github.com/supercent-io/skills-template)GitHub Stars58First SeenJan 24, 2026Security Audits[Gen Agent Trust HubPass](/supercent-io/skills-template/api-design/security/agent-trust-hub)[SocketPass](/supercent-io/skills-template/api-design/security/socket)[SnykPass](/supercent-io/skills-template/api-design/security/snyk)Installed oncodex11.1Kgemini-cli11.0Kopencode11.0Kgithub-copilot11.0Kcursor11.0Kamp11.0K

---
*Source: https://skills.yangsir.net/skill/sm-api-design*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-api-design/markdown*