mcpField
R
rest-api-design

rest-api-design

github.com/secondsky开发240594 次安装5 周前更新
代码仓库

关于 rest-api-design

面向 API 开发者的 REST 设计指南，涵盖资源命名、HTTP 方法、状态码、响应结构和查询参数，并介绍版本管理、分页及 OpenAPI/Swagger 文档实践。

主要功能

  1. 01使用名词和层级命名资源
  2. 02按操作选择 HTTP 方法
  3. 03选择合适的状态码
  4. 04设计响应结构和分页
  5. 05支持筛选、排序和字段选择
  6. 06编写文档并管理 API 版本

适用场景

  1. 01规划资源路径和端点操作
  2. 02统一 API 成功响应与错误响应
  3. 03为集合接口添加分页和查询选项
  4. 04制定 API 版本并准备文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/secondsky/claude-skills --skill rest-api-design

安装后在 Claude Code 中输入/rest-api-design确认已加载。

详细介绍

REST API 设计

遵循适当的约定和开发者体验来设计 RESTful API。

资源命名

# Good - nouns, plural, hierarchical
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/users
PATCH  /api/users/123
DELETE /api/users/123

# Bad - verbs, actions in URL
GET    /api/getUsers
POST   /api/createUser
POST   /api/users/123/delete

HTTP 方法

方法用途幂等
GET读取资源是
POST创建资源否
PUT替换资源是
PATCH部分更新是
DELETE删除资源是

状态码

代码含义用途
200成功GET、PATCH 成功
201已创建POST 成功
204无内容DELETE 成功
400错误请求验证错误
401未授权缺少身份验证信息
403禁止访问权限不足
404未找到资源不存在
429请求过多请求频率受限

响应格式

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John",
      "email": "[email protected]"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

集合响应

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2"
  }
}

查询参数

GET /api/products?category=electronics    # Filtering
GET /api/products?sort=-price,name        # Sorting
GET /api/products?page=2&limit=20         # Pagination
GET /api/products?fields=id,name,price    # Field selection

最佳实践

  • 使用名词表示资源，而非动词
  • 通过 URL 路径对 API 进行版本控制（/api/v1/）
  • 返回适当的状态码
  • 为集合提供分页
  • 使用 OpenAPI/Swagger 编写文档

评论

支持 Markdown