使用JSON作为API请求参数的格式（为我的Web应用程序设计API）

Question

我正在为我的网络应用设计API，而且我们的内容相当复杂。例如，您可以拥有一个包含多个子对象的Wiki页面，如标签，多个单独的内容区域等。

我不想处理像tag_N或tag []这样命名params的复杂，kludgy方式。

我也想到我们的对象可以完美地表达为JSON。事实上，这是我们的回应格式。如果您执行GET，则会收到JSON格式的对象。

要求在JSON中指定对象的POST和PUT主体是否合理？例如，像这样：

{
 'name' : 'My Page',
 'body' : 'Some page body',
 'tags' : ['tag1', 'tag2', 'tag3']
}

而不是

name=My%20Page&body=Some%20page%20body&tag[]=tag1&tag[]=tag2&tag[]=tag3

这是一个非常简化的例子。在许多情况下，我们使用包含子对象数组的复杂对象，这些子对象本身也包含子对象。使用JSON进行描述相当简单，但使用查询字符串样式参数非常困难。

所以，主要的问题是：如果我们要求POST主体是一个JSON字符串，那是不合理的吗？它远远超出HTTP API的标准吗？作为API使用者的作者，您是否会因具有此类要求的API而被推迟？

Answer 1

这不是没有道理的。您可能在这里混合了一些东西：（a）数据格式，（b）编码，以及（c）REST设计理念。

一般来说，我建议如下：

• 数据格式应该是一致的（例如，JSON作为资源上所有CRUD方法的基础;如果您支持XML也会很好，因为它无处不在 - 许多框架会自动为您执行此操作）

• 编码应与数据传输格式分开;例如，URL的编码与主体编码略有不同。不要将其与数据格式混淆。

• 建议您尽可能将资源建模为REST-ful。在大多数情况下，使用POST进行创建，使用GET进行读取，使用PUT进行更新，使用DELETE进行删除

Answer 2

这是JAX-RS / REST API的典型特征。