http - 使用 JSON 作为 API 请求参数的格式(为我的网络应用程序设计 API)

Question

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

我不想处理复杂、笨拙的参数命名方式，例如 tag_N 或 tag[]。

我还想到，我们的对象可以用 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 body是一个JSON字符串，这不合理吗？它是否超出了 HTTP API 的规范？作为 API 使用者的作者，您会被具有这样要求的 API 吓跑吗？

Answer 1

这不无道理。您可能会在这里混合一些东西:(a) 数据格式，(b) 编码，以及 (c) REST 设计理念。

一般来说，我会建议如下:

• 数据格式应保持一致(例如，JSON 作为资源上所有 CRUD 方法的基础；如果您也支持 XML 就更好了，因为它无处不在——许多框架会自动为您执行此操作)

• 编码应该和数据传输格式分开；例如，URL 的编码与正文编码略有不同。不要将它与数据格式混淆。

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