SuperAPI AI Directory

endpoint-design

Coding & development

View repository

Updated 10-16 09:30

About this skill

Endpoint Design

References:RFC 7231 HTTP/1.1 Semantics、GitHub REST API Guidelines

Use Cases

  • Endpoint list after resource modeling
  • Method + path design for a single endpoint
  • HTTP status code selection
  • Endpoint naming conventions

Core Principles

1. 用 HTTP 方法表达动作
   GET / POST / PUT / PATCH / DELETE 各有语义

2. 用 HTTP 状态码表达结果
   不要用 200 包装所有错误
  1. Use nouns in URL paths Express actions through the method

  2. Consistency first Use the same naming convention across the entire API


## HTTP 方法语义

| 方法 | 用途 | 幂等 | 安全 |
|------|------|------|------|
| GET | 查询资源 | ✅ | ✅ |
| POST | 创建资源 / 触发动作 | ❌ | ❌ |
| PUT | 完全替换资源 | ✅ | ❌ |
| PATCH | 部分更新资源 | ❌* | ❌ |
| DELETE | 删除资源 | ✅ | ❌ |
| HEAD | 查询头部(如检查存在) | ✅ | ✅ |
| OPTIONS | 查询支持的方法 | ✅ | ✅ |

*PATCH 不严格幂等,但可设计为幂等(如带 If-Match)

```text
幂等:多次调用结果相同(可重试)
安全:不修改服务器状态(可缓存)

HTTP Status Codes

2xx Success

200 OK                  请求成功(GET/PUT/PATCH 默认)
201 Created             资源已创建(POST 创建)
202 Accepted            已接收,异步处理中
204 No Content          成功但无返回(DELETE 默认)

3xx Redirection

301 Moved Permanently   永久迁移
302 Found               临时重定向
304 Not Modified        未修改(缓存生效)

4xx Client Errors

400 Bad Request         请求格式错误 / 参数错误
401 Unauthorized        未认证(缺 token / token 无效)
403 Forbidden           已认证但无权限
404 Not Found           资源不存在
405 Method Not Allowed  方法不支持
409 Conflict            冲突(如重复创建 / 版本冲突)
410 Gone                资源已永久删除
422 Unprocessable Entity 校验失败
429 Too Many Requests   限流

5xx Server Errors

500 Internal Server Error  服务器异常
502 Bad Gateway            网关错误
503 Service Unavailable    服务不可用
504 Gateway Timeout        网关超时

Naming Conventions

路径:
  - 复数(users / orders)
  - 小写
  - 连字符分隔(reset-password 而非 resetPassword)
  - 不带后缀(/users 不是 /users.json)

查询参数:
  - snake_case 或 camelCase(团队选一种坚持用)
  - 布尔值用 true/false(不要 1/0)

Header:
  - 标准 Header(Authorization / Content-Type)
  - 自定义用 X-(如 X-Request-Id)— 但 RFC 6648 已不推荐 X- 前缀

Standard CRUD Endpoints

查询列表:
  GET /resources
  GET /resources?page=1&page_size=20

查询单个:
  GET /resources/{id}

创建:
  POST /resources
  → 201 Created + 资源完整内容
  → Header: Location: /resources/{new-id}

完全替换:
  PUT /resources/{id}
  → 200 OK + 替换后的资源

部分更新:
  PATCH /resources/{id}
  → 200 OK + 更新后的资源

删除:
  DELETE /resources/{id}
  → 204 No Content(默认)
  → 200 OK + 被删除的资源(如需要)

Endpoint List Output

## 端点清单:[模块名]

| Method | Path | 用途 | 调用方 | 权限 | 成功状态码 | 失败状态码 | 幂等 | Mock |
|--------|------|------|--------|------|-----------|-----------|------|------|
| GET | /users | 查询用户列表 | 前端/后台 | admin | 200 | 401/403/500 | ✅ | ✅ |
| POST | /users | 创建用户 | 前端 | guest | 201 | 400/409/422/500 | ❌ | ✅ |
| GET | /users/{id} | 查询用户详情 | 前端 | self/admin | 200 | 401/403/404/500 | ✅ | ✅ |
| PATCH | /users/{id} | 更新用户 | 前端 | self/admin | 200 | 400/401/403/404/422/500 | ❌ | ✅ |
| DELETE | /users/{id} | 删除用户 | 后台 | admin | 204 | 401/403/404/500 | ✅ | ✅ |
| POST | /users/{id}/reset-password | 重置密码 | 后台 | admin | 202 | 401/403/404/500 | ❌ | ✅ |
| GET | /users/{id}/orders | 用户订单 | 前端 | self/admin | 200 | 401/403/404/500 | ✅ | ✅ |

Workflow

1. 读取资源清单(来自 resource-modeling)
2. 对每个资源应用标准 CRUD
3. 识别需要的特殊端点(动作/查询变体)
4. 决定 HTTP 方法
5. 列出可能的状态码
6. 标注权限和幂等
7. 输出端点清单
8. 转交 request-response 设计字段

Quality Self-Check

□ HTTP 方法用对了(不要 POST 做查询)
□ 状态码语义正确(不要 200 包错误)
□ 命名一致(复数 / 小写 / 连字符)
□ 幂等性标注清楚
□ 权限说明清楚
□ 是否考虑了 OPTIONS / HEAD

Common Pitfalls

  1. Using POST for queries——POST /users/search (should be GET /users?keyword=)
  2. Using GET to modify data——GET /users/{id}/activate (should be POST)
  3. DELETE returns 200 + full data——usually should be 204
  4. POST returns only the id after creation——the frontend has to GET again (should return the full resource)
  5. Misusing status codes——using 404 as 403, or 500 as 400
  6. Verbs in paths——/getUser / /createOrder
  7. Inconsistent methods——for the same "cancel", some use POST /cancel, others use PATCH status
  8. Using 404 for insufficient permissions——should use 403 (or 404 to hide existence)

Companion Templates

  • templates/endpoint-inventory-template.md — Endpoint list + HTTP method quick reference template

Collaboration with Other Skills

上游:
  resource-modeling → 提供资源清单

平行:
  request-response → 详细字段设计
  error-handling → 失败状态码细化
  auth-permission → 权限规则

下游:
  openapi-mock → 写入 OpenAPI 文档

Related References

  • references/endpoint-design-guide.md — URL naming, HTTP method semantics, status code usage, sub-resources, action-oriented endpoints, major vendor paradigms (GitHub / Stripe / Google AIP), self-check checklist