异步API多GET端点设计咨询：能否新增同requestId的独立GET端点

现有异步轮询API端点 #

1. POST 创建资源 #

请求示例：

curl -X POST https://api.example.com/v1/card/eligibility/

响应示例：

{
  "requestId": "12345678",
  "timestamp": "2021-11-01",
  ...
}

2. GET 获取资源（轮询用） #

请求示例：

curl -X GET https://api.example.com/v1/card/eligibility/12345678

响应示例：

{
  "eligibilityStatus": "Eligible/Ineligible",
  "orderData": "abc",
  ...
}

拟新增端点 #

请求示例：

curl -X GET https://api.example.com/v1/card/product-eligibility/12345678

响应示例：

{
  "product-eligibility": 111,
  "orderData": "abc",
  ...
}

结论与设计建议 #

完全可以新增这个独立GET端点，这种设计在异步API场景中十分常见，只要遵循以下实践要点即可：

• 语义一致性：/v1/card/product-eligibility/{requestId} 的路径能清晰反映"基于已有请求查询产品资格"的功能，语义明确，符合REST风格。
• 幂等性保障：严格遵循GET方法的幂等要求，确保多次调用该端点返回相同结果（除非底层关联资源状态发生合法变更）。
• 资源关联可靠性：确保后端能通过requestId精准关联到最初创建的资源，需保证requestId全局唯一，且存储层能通过它关联所有相关的资格数据。
• 响应格式统一：尽量和现有GET端点保持一致的响应结构风格，比如相同的orderData字段返回逻辑，降低客户端解析复杂度。
• 异步场景兼容（若需）：如果产品资格查询本身也是异步过程，需同步支持轮询状态返回（如pending状态），和现有轮询逻辑保持一致的状态码、响应字段规范。

如果后续有更多同类特定查询需求，也可考虑用查询参数扩展现有GET端点（如/v1/card/eligibility/{requestId}?type=product），但新增独立端点的方式在功能拆分清晰度、未来扩展性上更有优势，可根据API整体规划选择。

内容的提问来源于stack exchange，提问作者Ayushi Puri