RESTful API 和网页导航——它们兼容吗？

Question

也许我让事情变得混乱或过于复杂，但我正在努力开发一个支持 HTML 和 JSON 内容类型的 RESTful API。以一个简单的用户管理功能为例。我希望有一个如下所示的 API：

• GET /users：列出所有用户
• GET /users/{id}：查看单个用户
• POST /users：创建一个新用户

使用 JSON 有效负载向 /users 发布的程序化客户端会期望 201 Created 响应，其中包含 Location 标头，指定新创建用户的 URL，例如/用户/1。但是，通过 Web 浏览器创建用户的人将使用表单编码的有效负载发布到相同的 URL，并希望被重定向到用户列表页面，这需要 API 返回带有 Location 标头的 302/303 重定向/用户。

从纯粹概念的角度来看，API 会根据提交的内容类型做出不同的反应，这让我感到惊讶，我想知道这是否是糟糕的设计。再说一次，将程序化 API 和以 Web 为中心的 API 视为同一个 API 可能是错误的，我们不应该担心这些问题，而应该更多地担心为不同的客户提供良好的体验。

你怎么看？

Answer 1

您偶然发现了两个不同的问题。

第一，典型的网络浏览器是一个非常糟糕的 REST 客户端。

第二，Web 应用程序 API 不一定是 REST API（参见 #1）。

因此，你试图为两个主人服务的难题。

当涉及到工作流程等细节时，可以说表示与应用程序语义几乎没有关系，尤其是当您拥有同样丰富的媒体类型时（相对于受限制的媒体类型，如图像或其他）。

因此，在这些术语中，在给定相似的媒体类型的情况下让应用程序表现不同确实是不合适的。

另一方面，媒体类型是请求的另一个方面，它会影响后端的操作。例如，您可以请求一个省略的“lite”数据类型，该数据类型可能无法提供更丰富的媒体类型所提供的指向 api 其他部分的链接，或者您的授权级别是您可以查看哪些数据的一个因素，以及还有哪些其他关系可用，甚至根本支持哪些媒体类型。

因此，请求有效负载的每个方面都可能对服务器的任何特定请求的特定语义和效果产生影响，这是公平的。在这种情况下，你的场景并没有真正离题。

最后，要通过文档来阐明您作为 API 设计者的意图。