api-design by supercent-io/skills-template
npx skills add https://github.com/supercent-io/skills-template --skill api-design资源命名:
/users 而非 /getUsers/users/{id}/users/{id}/postsHTTP 方法:
GET:检索资源(幂等)广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
POST:创建新资源PUT:替换整个资源PATCH:部分更新DELETE:删除资源(幂等)响应码:
200 OK:成功并返回响应体201 Created:资源创建成功204 No Content:成功但无响应体400 Bad Request:无效输入401 Unauthorized:需要身份验证403 Forbidden:无权限404 Not Found:资源不存在409 Conflict:资源冲突422 Unprocessable Entity:验证失败500 Internal Server Error:服务器错误REST 端点示例:
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} # 删除用户
请求示例:
POST /api/v1/users
Content-Type: application/json
{
"name": "John Doe",
"email": "john@example.com",
"role": "admin"
}
响应示例:
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/123
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
"role": "admin",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
错误响应格式:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "提供的输入无效",
"details": [
{
"field": "email",
"message": "邮箱格式无效"
}
]
}
}
查询参数:
GET /api/v1/users?page=2&limit=20&sort=-created_at&filter=role:admin
带分页的响应:
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 100,
"pages": 5
},
"links": {
"self": "/api/v1/users?page=2&limit=20",
"first": "/api/v1/users?page=1&limit=20",
"prev": "/api/v1/users?page=1&limit=20",
"next": "/api/v1/users?page=3&limit=20",
"last": "/api/v1/users?page=5&limit=20"
}
}
选项:
JWT 示例:
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
URL 版本控制(推荐):
/api/v1/users
/api/v2/users
请求头版本控制:
GET /api/users
Accept: application/vnd.api+json; version=1
创建 OpenAPI 3.0 规范:
openapi: 3.0.0
info:
title: User Management API
version: 1.0.0
description: API for managing users
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: List users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreate'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
format: email
created_at:
type: string
format: date-time
UserCreate:
type: object
required:
- name
- email
properties:
name:
type: string
email:
type: string
format: email
过滤:
GET /api/v1/users?role=admin&status=active
排序:
GET /api/v1/users?sort=-created_at,name
字段选择:
GET /api/v1/users?fields=id,name,email
批量操作:
POST /api/v1/users/batch
{
"operations": [
{"action": "create", "data": {...}},
{"action": "update", "id": 123, "data": {...}}
]
}
如果 REST 不合适,可以考虑 GraphQL:
type User {
id: ID!
name: String!
email: String!
posts: [Post!]!
createdAt: DateTime!
}
type Query {
users(page: Int, limit: Int): [User!]!
user(id: ID!): User
}
type Mutation {
createUser(input: CreateUserInput!): User!
updateUser(id: ID!, input: UpdateUserInput!): User!
deleteUser(id: ID!): Boolean!
}
每周安装量
11.5K
代码仓库
GitHub 星标数
88
首次出现
2026年1月24日
安全审计
安装于
codex11.4K
gemini-cli11.3K
opencode11.3K
github-copilot11.3K
cursor11.3K
amp11.3K
Resource naming :
/users not /getUsers/users/{id}/users/{id}/postsHTTP methods :
GET: Retrieve resources (idempotent)POST: Create new resourcesPUT: Replace entire resourcePATCH: Partial updateDELETE: Remove resources (idempotent)Response codes :
200 OK: Success with response body201 Created: Resource created successfully204 No Content: Success with no response body400 Bad Request: Invalid input401 Unauthorized: Authentication required403 Forbidden: No permission404 Not Found: Resource doesn't exist409 Conflict: Resource conflict422 Unprocessable Entity: Validation failed500 Internal Server Error: Server errorExample REST endpoint :
GET /api/v1/users # List users
GET /api/v1/users/{id} # Get user
POST /api/v1/users # Create user
PUT /api/v1/users/{id} # Update user
PATCH /api/v1/users/{id} # Partial update
DELETE /api/v1/users/{id} # Delete user
Request example :
POST /api/v1/users
Content-Type: application/json
{
"name": "John Doe",
"email": "john@example.com",
"role": "admin"
}
Response example :
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/123
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
"role": "admin",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
Error response format :
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input provided",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
Query parameters :
GET /api/v1/users?page=2&limit=20&sort=-created_at&filter=role:admin
Response with pagination :
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 100,
"pages": 5
},
"links": {
"self": "/api/v1/users?page=2&limit=20",
"first": "/api/v1/users?page=1&limit=20",
"prev": "/api/v1/users?page=1&limit=20",
"next": "/api/v1/users?page=3&limit=20",
"last": "/api/v1/users?page=5&limit=20"
}
}
Options :
Example with JWT :
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
URL versioning (recommended):
/api/v1/users
/api/v2/users
Header versioning :
GET /api/users
Accept: application/vnd.api+json; version=1
Create OpenAPI 3.0 specification:
openapi: 3.0.0
info:
title: User Management API
version: 1.0.0
description: API for managing users
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: List users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreate'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
format: email
created_at:
type: string
format: date-time
UserCreate:
type: object
required:
- name
- email
properties:
name:
type: string
email:
type: string
format: email
Filtering :
GET /api/v1/users?role=admin&status=active
Sorting :
GET /api/v1/users?sort=-created_at,name
Field selection :
GET /api/v1/users?fields=id,name,email
Batch operations :
POST /api/v1/users/batch
{
"operations": [
{"action": "create", "data": {...}},
{"action": "update", "id": 123, "data": {...}}
]
}
If REST doesn't fit, consider GraphQL:
type User {
id: ID!
name: String!
email: String!
posts: [Post!]!
createdAt: DateTime!
}
type Query {
users(page: Int, limit: Int): [User!]!
user(id: ID!): User
}
type Mutation {
createUser(input: CreateUserInput!): User!
updateUser(id: ID!, input: UpdateUserInput!): User!
deleteUser(id: ID!): Boolean!
}
Weekly Installs
11.5K
Repository
GitHub Stars
88
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex11.4K
gemini-cli11.3K
opencode11.3K
github-copilot11.3K
cursor11.3K
amp11.3K
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
138,300 周安装