设计用户管理REST API

# API Design for User Management ## API Overview This API is designed to manage users, allowing for standard operations such as create, read, update, and delete (CRUD) on user data. The API is structured in a RESTful manner, which provides a clear and consistent approach for accessing and manipulating resources. ## Endpoints ### 1. Create User - **Endpoint**: `POST /users` - **Description**: Creates a new user. #### Request Example ```http POST /users HTTP/1.1 Content-Type: application/json { "name": "John Doe", "email": "john.doe@example.com" } ``` #### Response Example ```http HTTP/1.1 201 Created Content-Type: application/json { "id": "123", "name": "John Doe", "email": "john.doe@example.com", "created_at": "2023-10-01T12:00:00Z" } ``` ### 2. Retrieve User - **Endpoint**: `GET /users/{id}` - **Description**: Retrieves a user by their ID. #### Request Example ```http GET /users/123 HTTP/1.1 Accept: application/json ``` #### Response Example ```http HTTP/1.1 200 OK Content-Type: application/json { "id": "123", "name": "John Doe", "email": "john.doe@example.com", "created_at": "2023-10-01T12:00:00Z" } ``` ### 3. Update User - **Endpoint**: `PUT /users/{id}` - **Description**: Updates details of an existing user. #### Request Example ```http PUT /users/123 HTTP/1.1 Content-Type: application/json { "name": "Jane Doe", "email": "jane.doe@example.com" } ``` #### Response Example ```http HTTP/1.1 200 OK Content-Type: application/json { "id": "123", "name": "Jane Doe", "email": "jane.doe@example.com", "created_at": "2023-10-01T12:00:00Z" } ``` ### 4. Delete User - **Endpoint**: `DELETE /users/{id}` - **Description**: Deletes a user by their ID. #### Request Example ```http DELETE /users/123 HTTP/1.1 ``` #### Response Example ```http HTTP/1.1 204 No Content ``` ## Error Handling The API will use standardized HTTP status codes to indicate the success or failure of requests. Common error responses include: - **400 Bad Request**: Invalid request format or missing required fields. - **404 Not Found**: User with specified ID not found. - **500 Internal Server Error**: Generic error when the server encounters an unexpected condition. ### Error Response Example ```http HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "Invalid user data", "details": "Email is required" } ``` ## Security Control Authentication is required to access these endpoints. This might involve: - **Basic Authentication**: Users will need to provide API keys or tokens for access. - **Bearer Tokens**: Using OAuth token-based access, recommended for scalable and secure access control. All endpoints should be accessed over HTTPS to ensure security and integrity of data using encryption. If applicable, roles and permissions should be checked on a per-endpoint basis to provide fine-grained access control.

# 用户管理API设计方案（RESTful风格） --- ## 1. 接口概述（API Overview） 本API用于管理用户信息，实现基本的用户数据增删改查（CRUD）操作。API 遵循 RESTful 设计规范，支持 JSON 格式数据交互，接口兼顾易用性与扩展性，适用于Web后台及移动端管理场景。 --- ## 2. 端点定义（Endpoints） | 方法 | 路径 | 说明 | |--------|--------------------|-------------------| | GET | /api/v1/users | 获取用户列表 | | POST | /api/v1/users | 创建新用户 | | GET | /api/v1/users/{id} | 获取指定用户详情 | | PUT | /api/v1/users/{id} | 更新指定用户信息 | | DELETE | /api/v1/users/{id} | 删除指定用户 | ### 数据结构（User） ```json { "id": "string (UUID)", "name": "string", "email": "string", "created_at": "string (ISO8601 日期时间)" } ``` --- ## 3. 请求示例（Request Example） ### 3.1 获取用户列表 ``` GET /api/v1/users Authorization: Bearer <token> ``` #### 支持分页参数（可选）： - page: 第几页 - limit: 每页条数 --- ### 3.2 创建新用户 ``` POST /api/v1/users Content-Type: application/json Authorization: Bearer <token> { "name": "张三", "email": "zhangsan@example.com" } ``` --- ### 3.3 获取指定用户详情 ``` GET /api/v1/users/9b5d1234-aaef-42e8-9105-c0b587cbe2ec Authorization: Bearer <token> ``` --- ### 3.4 更新指定用户信息 ``` PUT /api/v1/users/9b5d1234-aaef-42e8-9105-c0b587cbe2ec Content-Type: application/json Authorization: Bearer <token> { "name": "李四", "email": "lisi@example.com" } ``` --- ### 3.5 删除指定用户 ``` DELETE /api/v1/users/9b5d1234-aaef-42e8-9105-c0b587cbe2ec Authorization: Bearer <token> ``` --- ## 4. 响应示例（Response Example） ### 4.1 获取用户列表 ```json { "page": 1, "limit": 20, "total": 120, "users": [ { "id": "9b5d1234-aaef-42e8-9105-c0b587cbe2ec", "name": "张三", "email": "zhangsan@example.com", "created_at": "2024-05-28T09:33:00Z" }, ... ] } ``` --- ### 4.2 创建新用户 ```json { "id": "9b5d1234-aaef-42e8-9105-c0b587cbe2ec", "name": "张三", "email": "zhangsan@example.com", "created_at": "2024-06-15T08:30:00Z" } ``` --- ### 4.3 获取指定用户详情 ```json { "id": "9b5d1234-aaef-42e8-9105-c0b587cbe2ec", "name": "张三", "email": "zhangsan@example.com", "created_at": "2024-06-15T08:30:00Z" } ``` --- ### 4.4 更新指定用户 ```json { "id": "9b5d1234-aaef-42e8-9105-c0b587cbe2ec", "name": "李四", "email": "lisi@example.com", "created_at": "2024-06-15T08:30:00Z" } ``` --- ### 4.5 删除指定用户 ```json { "message": "User deleted successfully." } ``` --- ## 5. 错误处理机制（Error Handling） 所有错误均采用标准JSON结构返回，对应合适的HTTP状态码。 | HTTP状态码 | 说明 | 响应体结构示例 | |------------|---------------------|-----------------------------------------------------| | 400 | 请求参数错误 | {"error": "Invalid request", "details": "email is required"} | | 401 | 未授权/认证失败 | {"error": "Unauthorized"} | | 403 | 权限不足 | {"error": "Forbidden"} | | 404 | 资源不存在 | {"error": "User not found"} | | 409 | 资源冲突（如重复邮箱） | {"error": "Email already exists"} | | 500 | 服务器内部错误 | {"error": "Internal server error"} | --- ## 6. 安全控制（Authentication/Authorization） - 所有端点均要求通过 Bearer Token（如JWT）进行身份认证。 - 可扩展基于角色（RBAC）实现不同权限粒度（如管理员、普通用户）。 - 建议所有通信基于 HTTPS 协议。 --- ## 7. 版本控制（Versioning） - 通过URL路径方式体现版本号（如 /api/v1/），便于后续扩展和升级。 --- **备注：本方案可根据业务进一步拓展字段或接口，支持批量操作和更多筛选条件。**

# API Overview 该用户管理API用于支持用户的增删改查（CRUD）操作。API遵循RESTful风格，允许客户端通过HTTP请求与用户资源进行交互。 # Endpoints ### 1. 创建用户 - **Endpoint**: `POST /api/users` - **描述**: 创建一个新用户。 ### 2. 获取用户列表 - **Endpoint**: `GET /api/users` - **描述**: 获取所有用户的列表。 ### 3. 获取单个用户 - **Endpoint**: `GET /api/users/{id}` - **描述**: 根据用户ID获取特定用户的信息。 ### 4. 更新用户 - **Endpoint**: `PUT /api/users/{id}` - **描述**: 更新指定用户的信息。 ### 5. 删除用户 - **Endpoint**: `DELETE /api/users/{id}` - **描述**: 删除指定用户。 # Request Example ### 创建用户 ```json POST /api/users Content-Type: application/json { "name": "John Doe", "email": "john.doe@example.com" } ``` ### 更新用户 ```json PUT /api/users/1 Content-Type: application/json { "name": "John Doe Updated", "email": "john.doe.updated@example.com" } ``` # Response Example ### 获取用户列表 ```json GET /api/users Response: [ { "id": 1, "name": "John Doe", "email": "john.doe@example.com", "created_at": "2025-04-29T18:21:43+08:00" }, { "id": 2, "name": "Jane Smith", "email": "jane.smith@example.com", "created_at": "2025-04-29T18:21:43+08:00" } ] ``` ### 获取单个用户 ```json GET /api/users/1 Response: { "id": 1, "name": "John Doe", "email": "john.doe@example.com", "created_at": "2025-04-29T18:21:43+08:00" } ``` # Error Handling - **400 Bad Request**: 请求参数不合法。 - **404 Not Found**: 请求的用户ID不存在。 - **500 Internal Server Error**: 服务器内部错误。 # Security Control - **Authentication**: 所有请求需通过Bearer Token进行身份验证。 - **Authorization**: 确保用户有权限执行相应的操作。

# API Overview This API is designed to manage user data, providing endpoints for creating, reading, updating, and deleting users. It follows the RESTful architecture, using standard HTTP methods to perform CRUD operations on user resources. # Endpoints | Endpoint | Method | Description | |------------------|--------|----------------------------| | `/users` | POST | Create a new user | | `/users` | GET | Retrieve all users | | `/users/{id}` | GET | Retrieve a single user | | `/users/{id}` | PUT | Update a user | | `/users/{id}` | DELETE | Delete a user | # Request Example ## Create a New User (POST /users) ```json { "name": "John Doe", "email": "john.doe@example.com" } ``` ## Retrieve a Single User (GET /users/{id}) No request body required. ## Update a User (PUT /users/{id}) ```json { "name": "Jane Doe", "email": "jane.doe@example.com" } ``` ## Delete a User (DELETE /users/{id}) No request body required. # Response Example ## Successful Response (Status Code: 200 or 201) ### Create a New User (POST /users) ```json { "id": "1", "name": "John Doe", "email": "john.doe@example.com", "created_at": "2023-10-01T12:00:00Z" } ``` ### Retrieve All Users (GET /users) ```json [ { "id": "1", "name": "John Doe", "email": "john.doe@example.com", "created_at": "2023-10-01T12:00:00Z" }, { "id": "2", "name": "Jane Doe", "email": "jane.doe@example.com", "created_at": "2023-10-02T12:00:00Z" } ] ``` ### Retrieve a Single User (GET /users/{id}) ```json { "id": "1", "name": "John Doe", "email": "john.doe@example.com", "created_at": "2023-10-01T12:00:00Z" } ``` ### Update a User (PUT /users/{id}) ```json { "id": "1", "name": "Jane Doe", "email": "jane.doe@example.com", "created_at": "2023-10-01T12:00:00Z" } ``` ## Error Handling | Status Code | Error Code | Description | |-------------|------------|---------------------------------| | 400 | BAD_REQUEST | Invalid input data | | 401 | UNAUTHORIZED | Authentication failed | | 403 | FORBIDDEN | Authorization failed | | 404 | NOT_FOUND | User not found | | 500 | INTERNAL_SERVER_ERROR | Server error | ### Error Response Example ```json { "error": { "code": "BAD_REQUEST", "message": "Invalid email format" } } ``` # Security Control - **Authentication**: The API uses OAuth 2.0 for authentication. Clients must include a valid access token in the `Authorization` header. ```http Authorization: Bearer <access_token> ``` - **Authorization**: Access to certain endpoints may require specific roles or permissions. The server will enforce these checks based on the user's role associated with the access token. This API design ensures that user management operations are performed securely and efficiently, adhering to RESTful principles.