二进制数据的REST API设计

Question

这有点像重新发明轮子，但我正在尝试为REST API创建高级指南。例如，GET请求用于检索数据，POST请求用于创建对象或调用操作，PATCH请求用于更新对象的部分等。

我正在努力处理POST部分。原因如下：

• 如果我不考虑二进制数据，我宁愿所有POST请求主体都是JSON。请参阅PayPal REST API作为示例。我喜欢这个，因为它更具表现力，可以在NoSQL数据库中轻松转换。
• 但我确实需要一些 API操作来处理二进制数据。在这种情况下，我不确定JSON是否仍然有用......

我的问题是：

• 在API设计中标准化POST请求是否有意义？ 选项1 ：所有POST请求都使用Content-Type“application / x-www-form-urlencoded”或“multipart / form-data”。 选项2 ：所有POST请求都使用Content-Type“application / json”。
• 如果使用上面的选项2，我如何允许客户端发送二进制文件数据？

一个例子

为了澄清我的问题，让我们进行一次 POST / profiles 操作。如果没有二进制数据，“application / json”主体可能如下所示。

{
  firstName: "Yours",
  lastName: "Truly"
}

但是如果用户需要包含二进制内容，则“multipart / form-data”主体看起来像这样，并且请求中稍后会有名为photo的输入的二进制内容。

firstName=Yours
lastName=Truly

Answer 1

这里没有完美的解决方案-这是REST开始受到限制的地方之一。正如您所描述的，能够对所有请求使用JSON进行标准化，同时还能够将二进制输入添加到某些请求中，这将是很好的。但是，为了将二进制输入与application / json输入一起传递，用户必须提交包含完整JSON部分和二进制部分的多部分请求，这比使用表单数据麻烦。

一个考虑因素是JSON是否可能变成分层结构-表单数据字段也无法扩展以表示更复杂的数据结构，因此，对于这些对象，最好使用真正的application / json部分，尤其是当您试图保持与不需要二进制输入的另一个端点的一致性。

另一个要考虑的因素是您是否要为客户提供语言本机SDK。这些SDK可以抽象出有关多部分表单请求的更加混乱和繁琐的细节，从而使您能够保持一致性和灵活性，而不会出现太多可用性问题。