一键在 Manus 中运行任何 Skill

api-design

星标4

分支2

更新时间2026年6月20日 02:02

REST/gRPC API design, versioning strategies, error codes, request/response contracts, backward compatibility, rate limiting, OpenAPI specifications. Use when designing APIs, defining contracts, planning versioning, or ensuring API consistency.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

saitarrun

saitarrun/devforge-ai

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

Skill: API Design

Design APIs as contracts. Versions matter. Backward compatibility is non-negotiable.

REST Principles

Noun-based URLs: /users not /getUsers
HTTP methods: GET (read), POST (create), PUT (update), DELETE (remove)
Status codes: 200 (OK), 201 (created), 400 (bad request), 401 (auth), 404 (not found), 500 (error)
Consistency: Same patterns across all endpoints

Versioning Strategy

URL path (explicit, clear):

GET /api/v1/users   # v1 API
GET /api/v2/users   # v2 API (breaking change)

Header (less visible, prefer path):

GET /api/users
Header: API-Version: 2

Breaking Changes = Major Version

v1.0 → v2.0: User response format changed
v1.1 → v1.2: New optional field added (backward-compatible)
v1.0 → v1.1: Bug fix (patch)

API Contract (OpenAPI/Swagger)

paths:
  /users/{id}:
    get:
      summary: Get user
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Not found

Error Responses

{
  "error": "not_found",
  "message": "User not found",
  "code": 404,
  "details": {
    "resource": "user",
    "id": "user-123"
  }
}

Rate Limiting

Header: X-RateLimit-Limit: 1000
Header: X-RateLimit-Remaining: 999
Header: X-RateLimit-Reset: 1640000000

Pagination

GET /users?page=2&page_size=10

Response:
{
  "items": [...],
  "total": 245,
  "page": 2,
  "page_size": 10,
  "has_next": true
}

Deprecation Plan

1. Announce: Email, docs, API response header
2. Timeline: 6 months before removal
3. Header: X-API-Warn: "endpoint deprecated, use /v2/..."
4. Support: v1 and v2 endpoints run in parallel
5. Remove: After timeline expires

Status: Ready for API design
Best for: API contracts, versioning, error handling

同仓库更多 Skills

同仓库

to-issues

saitarrun/devforge-ai

Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.

2026-06-204

to-prd

saitarrun/devforge-ai

Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.

2026-06-204

code-quality

saitarrun/devforge-ai

This skill should be used when implementing code quality standards, setting up linting/testing/security scans, enforcing coverage thresholds, or establishing CI/CD guardrails.

2026-06-204

architecture

saitarrun/devforge-ai

This skill should be used when the user asks to "design a system", "architecture", "ADR", "system design", "tech stack", "choose between approaches", "coupling", "service granularity", "blueprint", "component design", "API contract", "schema design", "trade-offs", or discusses "monolith", "microservices", "fitness functions", or architectural decisions.

2026-06-204

cicd

saitarrun/devforge-ai

This skill should be used when the user mentions keywords related to cicd.

2026-06-204

cloud-infra

saitarrun/devforge-ai

This skill should be used when the user mentions keywords related to cloud-infra.

2026-06-204

name	api-design
description	REST/gRPC API design, versioning strategies, error codes, request/response contracts, backward compatibility, rate limiting, OpenAPI specifications. Use when designing APIs, defining contracts, planning versioning, or ensuring API consistency.
version	1.0.0

Skill: API Design

Design APIs as contracts. Versions matter. Backward compatibility is non-negotiable.

REST Principles

Noun-based URLs: /users not /getUsers
HTTP methods: GET (read), POST (create), PUT (update), DELETE (remove)
Status codes: 200 (OK), 201 (created), 400 (bad request), 401 (auth), 404 (not found), 500 (error)
Consistency: Same patterns across all endpoints

Versioning Strategy

URL path (explicit, clear):

GET /api/v1/users   # v1 API
GET /api/v2/users   # v2 API (breaking change)

Header (less visible, prefer path):

GET /api/users
Header: API-Version: 2

Breaking Changes = Major Version

v1.0 → v2.0: User response format changed
v1.1 → v1.2: New optional field added (backward-compatible)
v1.0 → v1.1: Bug fix (patch)

API Contract (OpenAPI/Swagger)

paths:
  /users/{id}:
    get:
      summary: Get user
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Not found

Error Responses

{
  "error": "not_found",
  "message": "User not found",
  "code": 404,
  "details": {
    "resource": "user",
    "id": "user-123"
  }
}

Rate Limiting

Header: X-RateLimit-Limit: 1000
Header: X-RateLimit-Remaining: 999
Header: X-RateLimit-Reset: 1640000000

Pagination

GET /users?page=2&page_size=10

Response:
{
  "items": [...],
  "total": 245,
  "page": 2,
  "page_size": 10,
  "has_next": true
}

Deprecation Plan

1. Announce: Email, docs, API response header
2. Timeline: 6 months before removal
3. Header: X-API-Warn: "endpoint deprecated, use /v2/..."
4. Support: v1 and v2 endpoints run in parallel
5. Remove: After timeline expires

Status: Ready for API design
Best for: API contracts, versioning, error handling