API Design

REST API设计模式,包括资源命名、状态码、分页、过滤、错误响应、版本控制和生产API的速率限制。

2,037 stars 332 forksSoftware Development Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add xu-xiang/everything-claude-code-zh

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add xu-xiang/everything-claude-code-zh --skill api-design
Manual install
git clone --depth 1 https://github.com/xu-xiang/everything-claude-code-zh.git /tmp/everything-claude-code-zh
mkdir -p ~/.claude/skills
cp -r /tmp/everything-claude-code-zh/docs/zh-CN/skills/api-design ~/.claude/skills/api-design

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# API 设计模式

用于设计一致、对开发者友好的 REST API 的约定和最佳实践。

## 何时启用

* 设计新的 API 端点时
* 审查现有的 API 契约时
* 添加分页、过滤或排序功能时
* 为 API 实现错误处理时
* 规划 API 版本策略时
* 构建面向公众或合作伙伴的 API 时

## 资源设计

### URL 结构

```
# Resources are nouns, plural, lowercase, kebab-case
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# Sub-resources for relationships
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# Actions that don't map to CRUD (use verbs sparingly)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
```

### 命名规则

```
# GOOD
/api/v1/team-members          # kebab-case for multi-word resources
/api/v1/orders?status=active  # query params for filtering
/api/v1/users/123/orders      # nested resources for ownership

# BAD
/api/v1/getUsers              # verb in URL
/api/v1/user                  # singular (use plural)
/api/v1/team_members          # snake_case in URLs
/api/v1/users/123/getOrders   # verb in nested resource
```

## HTTP 方法和状态码

### 方法语义

| 方法 | 幂等性 | 安全性 | 用途 |
|--------|-----------|------|---------|
| GET | 是 | 是 | 检索资源 |
| POST | 否 | 否 | 创建资源,触发操作 |
| PUT | 是 | 否 | 完全替换资源 |
| PATCH | 否\* | 否 | 部分更新资源 |
| DELETE | 是 | 否 | 删除资源 |

\*通过适当的实现,PATCH 可以实现幂等

### 状态码参考
Read the full skill on GitHub

Details

Skill name
api-design
Path
docs/zh-CN/skills/api-design/SKILL.md
License
MIT
Repo updated
5 March 2026

FAQ

What does the API Design skill do?

REST API设计模式,包括资源命名、状态码、分页、过滤、错误响应、版本控制和生产API的速率限制。

How do I install the API Design skill?

Claude Code plugin: /plugin marketplace add xu-xiang/everything-claude-code-zh. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is API Design popular?

It lives in xu-xiang/everything-claude-code-zh, which has 2,037 GitHub stars and 332 forks.

Related skills

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.