RESTful接口中user/{id}/resource对应下载端点的正确命名方法

RESTful 设计的核心原则是URI 仅用于标识资源，动作通过 HTTP 方法定义，因此在 URI 中加入 download 这类动作词汇、或者拼接无层级语义的 resourcedownload 都不符合规范，以下是合规的实现方案：

• 首选方案：复用现有资源端点，通过请求头区分场景
  直接使用现有端点 GET /user/{id}/resource，通过 HTTP 内容协商机制区分返回形式：
  • 客户端需要下载资源时，携带请求头 Accept: 对应文件的MIME类型（通用场景可填 application/octet-stream），服务端返回文件流的同时，携带响应头 Content-Disposition: attachment; filename="自定义文件名" 触发下载行为
  • 客户端需要获取资源的结构化元数据时，携带请求头 Accept: application/json，服务端返回 JSON 格式的资源信息即可
    该方案完全符合 REST 规范，无需新增额外端点。
• 兼容方案：通过后缀或查询参数指定返回格式
  如果服务端无法兼容同一端点返回多类格式，可以用两种方式做区分，均不会破坏资源的层级语义：
  • 加格式后缀：GET /user/{id}/resource.pdf（后缀对应实际文件格式）
  • 加查询参数：GET /user/{id}/resource?format=pdf
• 变通方案：用查询参数控制下载行为
  如果业务场景中下载的是经过额外加工的资源产物，和常规资源返回的内容差异较大，可以用查询参数标记下载需求：GET /user/{id}/resource?download=true，该方案是业界普遍接受的变通实现，比在路径中加入动作词更合理。

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