如何设计需要处理上传文件需求的restful 查询接口呢

Question

我需要一个实现两个功能，需要使用 restful 风格

• 功能一：查询 GET api/documents/

  即搜索功能：用户需要上传一个文本文件，通过这个文件去搜索有没有相似的文件，类似论文查重的功能

• 功能二：新增 POST api/documents/

  用户上传一个文本文件，并作为母本保存

我现在的问题是，查询应该使用 get 操作，但是 get 请求如何上传文件呢？

如果改为 post 的话，会和新增功能冲突，我该如何解决这个矛盾呢？如何平衡这两者，如何设计 API 呢

简单来说我就是觉得使用 POST 来查询不够 restful

Answer 1

软件工程没有银弹，RESTful 也不是万能灵药。

如果文件比较小，你可以把整个文件流转为 Base64 后拼接在 URL 查询参数里。

如果没啥限制的话，大可不必非得往 RESTful 上靠。

P.S. 如果是我来设计，可能会把文件上传跟查询两个接口分开。比如文件上传是 [POST] /file/upload，返回一个 file_id 字段；然后查询时 [GET] /documents?filter=file_content&file_id=myFileId。

Answer 2

RESTful 适合的是对 “资源” 的一系列操作，在操作的对象不能定义成一个资源时就说明他不合适了。

文件上传 是把“文件”当作一个对象来看，那他就应该是一个单独的实体，而不是和其他表单混在一起。

对于你这个需求来说，用户上传文件就应该设计成一个单独的接口，在上传文件后，你可以计算并返回文件的 hash ，然后用 hash 再去检索。