使用方法
- 复制安装命令，在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物，并对照来源检查输出。
npx skills add https://github.com/secondsky/claude-skills --skill rest-api-design开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况，不等于独立质量或安全测试。
仓库原始内容
按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。
REST API Design
Design RESTful APIs with proper conventions and developer experience.
Resource Naming
# 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/deleteHTTP Methods
| Method | Purpose | Idempotent |
|---|---|---|
| GET | Read resource | Yes |
| POST | Create resource | No |
| PUT | Replace resource | Yes |
| PATCH | Partial update | Yes |
| DELETE | Remove resource | Yes |
Status Codes
| Code | Meaning | Use For |
|---|---|---|
| 200 | OK | Successful GET, PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Validation errors |
| 401 | Unauthorized | Missing auth |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 429 | Too Many Requests | Rate limited |
Response Format
json
{
"data": {
"id": "123",
"type": "user",
"attributes": {
"name": "John",
"email": "john@example.com"
}
},
"meta": {
"requestId": "req_abc123"
}
}Collection Response
json
{
"data": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
},
"links": {
"self": "/api/users?page=1",
"next": "/api/users?page=2"
}
}Query Parameters
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 selectionBest Practices
- Use nouns for resources, not verbs
- Version API via URL path (
/api/v1/) - Return appropriate status codes
- Include pagination for collections
- Document with OpenAPI/Swagger
