API设计疑问：同资源不同返回方式选查询参数还是独立端点？

1. 异步接口设计方案合理性 #

这个方案是合理的：

• 生成CSV文件属于耗时操作（尤其是数据量较大时），用异步模式返回202 Accepted告知客户端请求已接收并处理，避免客户端长时间阻塞等待，符合RESTful API的状态码使用规范。
• 完成后返回200 OK和GCS下载链接，清晰传递操作结果，客户端可以直接通过链接获取文件，流程顺畅。

2. 端点选择建议：优先独立端点 /my/resource/csv-link #

对比两种方案的优缺点：

查询参数方案（/my/resource?format=csv-link）的问题 #

• 虽然符合同资源不同格式的逻辑，但会导致同一接口出现两种完全不同的行为和返回类型：原接口同步返回JSON格式的资源数据，新增逻辑则是异步返回下载链接，这种行为不一致会直接导致OpenAPI自动生成TypeScript类型时出现冲突，类型定义混乱。
• 异步生成CSV的逻辑会和原同步接口的逻辑耦合，后续维护、修改或扩展时容易相互影响，增加复杂度。

独立端点方案（/my/resource/csv-link）的优势 #

• 职责单一清晰：原接口专注于返回JSON资源，新接口专门处理CSV文件的异步生成与下载链接返回，接口行为明确，开发者使用时不会产生歧义。
• 避免类型冲突：独立端点可以单独定义返回类型，OpenAPI生成TypeScript类型时完全独立，不会影响原接口的类型定义。
• 扩展性更好：如果后续需要新增其他格式（如Excel）的导出功能，可以直接沿用/my/resource/xxx-link的结构，保持API风格一致，无需修改原接口逻辑。

综上，推荐使用独立端点 /my/resource/csv-link。

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