mcpField
R
rest-api-design

rest-api-design

github.com/aj-geddes开发3732.1k 次安装34 周前更新
代码仓库

关于 rest-api-design

面向新建或改造 REST API 的开发者设计技能，聚焦一致的资源导向端点、请求与响应格式、版本管理及 API 文档。

主要功能

  1. 01资源命名与 HTTP 方法
  2. 02查询参数和响应格式指导
  3. 03状态码与版本管理
  4. 04身份验证和限流指导
  5. 05OpenAPI 文档

适用场景

  1. 01为新的 REST API 设计端点
  2. 02统一请求与响应格式
  3. 03规划 API 版本管理
  4. 04使用 OpenAPI 编写 API 文档

安装

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

$npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill rest-api-design

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
complete-example-expressjs.md
http-status-codes.md
openapi-documentation.md
query-parameters.md
request-examples.md
resource-naming.md
response-formats.md
scripts/
validate-api.sh
templates/
api-scaffold.yaml

详细介绍

REST API 设计

目录

概述

设计直观、一致且遵循资源导向架构行业最佳实践的 REST API。

适用场景

  • 设计新的 RESTful API
  • 创建端点结构
  • 定义请求/响应格式
  • 实现 API 版本控制
  • 编写 API 规范文档
  • 重构现有 API

快速开始

最小可运行示例：

✅ Good Resource Names (Nouns, Plural)
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/products
DELETE /api/products/456

❌ Bad Resource Names (Verbs, Inconsistent)
GET    /api/getUsers
POST   /api/createProduct
GET    /api/user/123  (inconsistent singular/plural)

参考指南

references/ 目录中的详细实现：

指南内容
资源命名资源命名、HTTP 方法与操作
请求示例请求示例
查询参数查询参数
响应格式响应格式
HTTP 状态码HTTP 状态码、API 版本控制、身份验证与安全性、速率限制标头
OpenAPI 文档OpenAPI 文档
完整示例：Express.jsconst express = require("express");

最佳实践

✅ 应该做
  • 使用名词表示资源，而非动词
  • 使用复数名称表示集合
  • 遵循一致的命名规范
  • 返回适当的 HTTP 状态码
  • 为集合提供分页
  • 提供筛选和排序选项
  • 为 API 进行版本控制
  • 使用 OpenAPI 编写详尽文档
  • 使用 HTTPS
  • 实施速率限制
  • 提供清晰的错误消息
  • 日期使用 ISO 8601 格式
❌ 不应该做
  • 在端点名称中使用动词
  • 出错时返回 200
  • 不必要地暴露内部 ID
  • 资源嵌套过深（最多 2 层）
  • 使用不一致的命名
  • 忘记身份验证
  • 返回敏感数据
  • 不进行版本控制就破坏向后兼容性

评论

支持 Markdown