REST API：请求正文为 JSON 或纯 POST 数据？

Posted 2023-02-24

【中文标题】REST API：请求正文为 JSON 或纯 POST 数据？

【英文标题】：REST API: Request body as JSON or plain POST data?

【发布时间】：2012-04-04 02:26:06

【问题描述】：

我目前正在构建一个 REST API。目前所有 GET 方法都使用 JSON 作为响应格式。 POST 和 PUT 操作的最佳实践是什么？在请求正文或普通 POST 中使用 JSON？我找不到关于这件事的任何信息。

我看到 Twitter 使用 POST 例如： https://dev.twitter.com/docs/api/1/post/direct_messages/new

使用 JSON 格式有什么好处？我从 github 获得的 API 控制器（已完成一半）需要 JSON。真的很想知道为什么我会选择使用它。

【参考方案1】：

POST、PUT、GET 都是 HTTP 动词，它们本身并不表示传输数据的格式，因此 没有 POST 格式。这意味着您可以选择任何方式对数据进行编码。

现在，您决定采用哪种格式应该真的更多地取决于您的 API 通常如何使用。如果它主要是从网络浏览器提交表单，那么使用表单字段编码可能是最合理的做法，因为它使客户端的交互更容易。

另一方面，如果您主要从 AJAX 调用接收 JSON 数据，那么接收 JSON 格式可能是有意义的。如果您将两者都做，那么您没有任何理由不能接受两种格式的数据。

要考虑的另一个方面是您将来回传递的数据结构的复杂性。表单编码（也类似于查询字符串编码）是一种键值结构，而 JSON（或 XML）允许更丰富的数据结构。

最后，无论您在服务器端还是在客户端，都选择最简单的方法（因为我假设您还将编写相关 API 的主要客户端使用者）。简单总是优先于复杂性，直到您可以明确地证明更多的复杂性会给您带来可衡量的好处。

另外，我要提到的最后一件事是，REST 不仅仅是关于干净的 URL 或正确使用 HTTP 动词。这些方面真的只是锦上添花。 REST 架构背后的核心思想是 Hypertext is the engine of application state。通过简单地跟踪服务器响应中的 URL，一个好的客户端可以了解所有可用的操作，并且不需要知道除了基本 URL 之外的任何内容。其他一切都可以从中发现。再加上定义明确的内容类型，您就有了一个世界，其中许多客户端可以与许多服务器进行通信，所有服务器都使用相同的“语言”，并且客户端不需要了解任何关于除了基本 URL 和内容类型之外的服务器（反之亦然）。这就是 REST 的全部意义所在。

【讨论】：

我想不出比这更明确的答案了。我会考虑什么最适合我的情况。由于原生 javascript 兼容性，可能是 JSON。感谢您的宝贵时间！

【参考方案2】：

这取决于您要交换的数据。如果它是一个复杂的结构，您需要以结构化的方式（例如 XML 或 JSON）发送它。在 java web 应用程序中，json 更轻量级，因此它比 XML 更可取。

如果您想从表单“application/x-www-urlformencoded”类型发送一些字段，也可以使用。