RESTful API端点设计器

以下是一个关于订单管理的RESTful API设计，支持读取和更新操作:

1. API 基础信息

• 基础 URL: https://api.example.com
• 资源路径: /orders
• 数据格式: JSON
• 用户认证: 通过 Bearer Token 发送授权头进行认证 (Authorization: Bearer <token>)

2. API 端点设计

(1) 获取订单详情

• URL: /orders/{orderId}
• HTTP 方法: GET
• 功能: 根据订单 orderId 获取订单详细信息。
• 请求头:

  Authorization: Bearer <token>
  

• 请求参数:
  • 路径参数: orderId (表示特定订单的ID, 必须)
• 响应:
  • 成功 (状态码: 200 OK):

    {
      "status": "success",
      "data": {
        "orderId": "12345",
        "userId": "67890",
        "status": "completed",
        "items": [
          {
            "productId": "111",
            "quantity": 1,
            "price": 100
          },
          {
            "productId": "222",
            "quantity": 2,
            "price": 200
          }
        ],
        "totalPrice": 500
      }
    }
    

  • 失败:
    • 未授权 (状态码: 401 Unauthorized):

      {
        "status": "error",
        "message": "Authentication token is missing or invalid"
      }
      

    • 无权限访问 (状态码: 403 Forbidden):

      {
        "status": "error",
        "message": "You are not authorized to access this order"
      }
      

    • 未找到订单 (状态码: 404 Not Found):

      {
        "status": "error",
        "message": "Order not found"
      }
      

(2) 更新订单

• URL: /orders/{orderId}
• HTTP 方法: PUT
• 功能: 更新指定订单信息，普通用户仅可更新特定字段(如收货地址)。
• 请求头:

  Authorization: Bearer <token>
  

• 请求参数:
  • 路径参数: orderId (表示特定订单的ID, 必须)
• 请求体 (示例): 用户更新其订单中“地址”字段：

  {
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "zipCode": "10001"
    },
    "status": "pending"
  }
  

  • 用户只能更新允许的字段，例如: 收货地址(address)或自定义字段。禁止更新付款状态或敏感字段。
• 响应:
  • 成功 (状态码: 200 OK):

    {
      "status": "success",
      "data": {
        "orderId": "12345",
        "status": "updated",
        "address": {
          "street": "123 Main St",
          "city": "New York",
          "zipCode": "10001"
        }
      }
    }
    

  • 失败:
    • 未授权 (状态码: 401 Unauthorized):

      {
        "status": "error",
        "message": "Authentication token is missing or invalid"
      }
      

    • 无权限访问 (状态码: 403 Forbidden):

      {
        "status": "error",
        "message": "You are not authorized to update this order"
      }
      

    • 请求格式错误或含有有禁止字段 (状态码: 400 Bad Request):

      {
        "status": "error",
        "message": "Invalid input data or you are trying to update restricted fields"
      }
      

3. 用户权限要求

• 普通用户:
  • 可以读取自己账户相关的订单 (GET /orders/{orderId})。
  • 只能更新允许字段，如订单地址 (PUT /orders/{orderId})。
  • 认证: 必须使用有效的 Bearer Token。
• 管理员:
  • 可以读取和更新所有订单。
  • 在更新订单时没有字段限制，但需要额外的管理员认证机制（如角色权限验证）。

小结

以上就是一个简洁的RESTful API设计，支持订单的读取与更新操作，并对用户权限进行了限制，保证了数据安全性且满足了普通用户的基本使用需求。

以下是一个为产品设计的 RESTful API 的详细说明，该 API 支持创建和读取操作，提供 URL 模式、HTTP 方法、请求/响应格式，并包含管理员访问权限的认证要求：

设定假设

1. 产品的资源名称为 Product。
2. RESTful API 需要支持创建（Create - POST）和读取（Read - GET）操作。
3. 只有拥有管理员权限的用户才能创建新产品（通过 admin 权限进行认证检查）。
4. 读取操作对所有用户公开，不需要身份验证。
5. API 返回的响应采用 JSON 格式。

1. API 端点说明

1.1 创建产品

• URL 模式: /api/products/
• HTTP 方法: POST
• 请求头:
  • Content-Type: application/json （请求体为 JSON 格式）
  • Authorization: Bearer <token> （只有管理员权限用户才能创建）
• 请求体格式: 提供新产品的信息，例如产品名称、描述、价格等：

  {
    "name": "string",       // 产品名称（必填）
    "description": "string", // 产品描述（选填）
    "price": "float"        // 产品价格（必填，正值）
  }
  

• 响应格式:
  • 成功创建： 状态码: 201 Created

    {
      "id": "uuid",         // 产品的唯一标识
      "name": "string",     // 产品名称
      "description": "string",
      "price": "float",
      "created_at": "ISO 8601 timestamp",
      "status": "success"
    }
    

  • 失败（如权限不足或无效请求体）： 状态码: 例如 401 Unauthorized 或 400 Bad Request

    {
      "error": "string",     // 错误描述
      "status_code": 401
    }
    

1.2 获取产品列表

• URL 模式: /api/products/

• HTTP 方法: GET

• 请求头: 可选 Authorization: Bearer <token>

• 查询参数: 可用的查询选项用于过滤返回的产品列表:

  • ?name=<部分名称>: 按名称进行模糊搜索
  • ?price_min=<金额>: 最低价格过滤
  • ?price_max=<金额>: 最高价格过滤

• 响应格式:

  • 成功： 状态码: 200 OK

    [
      {
        "id": "uuid",         // 产品的唯一标识符
        "name": "string",     // 产品名称
        "description": "string",
        "price": "float",
        "created_at": "ISO 8601 timestamp"
      },
      ...
    ]
    

  • 无数据时：

    []
    

  • 查询错误： 状态码: 400 Bad Request

    {
      "error": "string",
      "status_code": 400
    }
    

1.3 获取单个产品

• URL 模式: /api/products/{id}/
• HTTP 方法: GET
• 请求头: 可选 Authorization: Bearer <token>
• 路径参数:
  • {id}: 产品的唯一标识符（UUID 格式）
• 响应格式:
  • 成功： 状态码: 200 OK

    {
      "id": "uuid",         // 产品的唯一标识
      "name": "string",     // 产品名称
      "description": "string",
      "price": "float",
      "created_at": "ISO 8601 timestamp"
    }
    

  • 产品未找到： 状态码: 404 Not Found

    {
      "error": "Product not found",
      "status_code": 404
    }
    

2. 权限控制

创建操作的管理员权限验证

• 认证方式: 基于 Token 的 Bearer 身份认证
• 通过 Authorization 请求头传递 Token：

  Authorization: Bearer <token>
  

• 在服务器端校验 Token 是否有效，解码后检查用户是否拥有 admin 权限。

读取操作的公开权限

• 不需要身份认证，任何用户都可以访问。
• 如果某些敏感信息需要保护（如定价策略的查看限制），应增加对某些字段访问的控制。

3. 用于测试的示例

示例 1: 创建新产品

请求

POST /api/products/ HTTP/1.1
Host: api.example.com
Authorization: Bearer abc123token
Content-Type: application/json

{
  "name": "Wireless Headphones",
  "description": "Noise cancelling over-ear headphones.",
  "price": 199.99
}

响应

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "e217b630-21a3-11ee-be56-0242ac120002",
  "name": "Wireless Headphones",
  "description": "Noise cancelling over-ear headphones.",
  "price": 199.99,
  "created_at": "2023-10-31T12:00:00Z",
  "status": "success"
}

示例 2: 获取产品列表

请求

GET /api/products/?price_min=100 HTTP/1.1
Host: api.example.com

响应

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "e217b630-21a3-11ee-be56-0242ac120002",
    "name": "Wireless Headphones",
    "description": "Noise cancelling over-ear headphones.",
    "price": 199.99,
    "created_at": "2023-10-31T12:00:00Z"
  },
  {
    "id": "f318c740-21a3-11ee-be56-0242ac120002",
    "name": "Bluetooth Speaker",
    "description": "Portable speaker with high-quality sound.",
    "price": 149.99,
    "created_at": "2023-10-30T15:00:00Z"
  }
]

通过以上设计，你可以实现一个支持创建和读取产品的 RESTful API，同时包含管理员权限验证的具体逻辑。