REST API - 客户端如何知道向资源 POST 有效载荷的格式？

Question

REST API架构的目标之一是客户端和服务器的解耦。

在规划REST API时，我遇到的一个问题是：“客户端如何知道POST方法的有效负载是什么？”。

API需要以某种方式向UI通信，给出特定资源的POST方法的有效负载。否则，我们又回到了依赖必须具备的超出带宽知识以使用API并再次紧密耦合的状态。

因此，我的想法是，在资源的GET操作的API响应中提供构建该资源的POST方法的有效负载的规范。这将包括字段名称、数据类型、最大长度等信息。 这个人有类似的想法。

处理这个问题的正确方法是什么？大多数人只是依赖超出带宽的信息吗？在现实世界中，人们是如何解决这个问题的？ 编辑 我提出的解决此问题的方法在以下序列图中说明：

客户端和 API 服务是分开的。客户端知道：

1. 入口点
2. 如何通过超媒体导航 API。

以下是发生的事情：

1. 某人（用户）从客户端请求注册页面
2. 客户端从 API 请求入口点，并接收所有超媒体链接以及有关如何合法遍历它们的元数据。
3. 客户端根据与注册超媒体 POST 方法相关联的元数据构建注册表单。
4. 用户填写表单并提交。
5. 客户端使用正确的数据进行 POST 到 API，一切都很好。

没有神奇的 /meta 资源，也不需要使用方法来获取元数据。API 提供一切。

想法呢？

- richard

---

使用GET来获取元数据分享GET和POST的资源的问题在于，通常你会使用GET来检索你发布或列表中的widget。如果您要允许API完全驱动UI，则需要提供某种提供元数据的端点。我只是不会使用GET /widget。我会使用类似GET /widget/meta这样的东西。但是，正如其他人所说，这将使您的UI与API对元数据的实现耦合在一起。但是，如果您遵循某些规范（或创建一个规范），则您只与规范耦合。 - Byron Sommardahl

Answer 1

大多数人都依赖于带外信息。通常情况下这是可以接受的，因为大多数客户端不是动态构建的，而是静态的。他们依赖于已知的API部分，而不是HATEOAS驱动。

如果您正在开发或想要支持元数据驱动的客户端，那么是的，您需要提供该信息的模式。您链接的实现在快速浏览后似乎是合理的。请注意，您只是将问题转移了。客户端仍然需要知道如何解释元数据响应中的信息。

- Eric Stein

---

他们需要了解什么才能解释它？有效的回答已经完全定义好了。 - richard

它们现在与你的元数据端点和它所提供的响应紧密耦合。 - shieldstroy

@troylshields 元数据端点就是端点。客户端应该根据响应进行适应，就像http根据响应构建页面一样。 - richard

我同意@eric-stein的看法，你只是把问题转移了。 客户端并没有被动态构建，应该与REST服务紧密耦合的仅是一个接口，可以轻松替换。 - shieldstroy

@richard 在HTTP中，服务器和客户端共享带外信息 - HTTP规范。 <b> 表示加粗等。您的客户端和服务器需要共享带外信息，以便处理元数据内容。这就是我的全部意思。 - Eric Stein

Answer 2

你说得对，客户端应该理解响应中链接的语义，并从中选择合适的链接以实现其目标。客户端与API提供的语义耦合，而不是与API本身耦合。因此，例如，客户端不应从URI结构中检索信息，因为它与实际API紧密耦合。

我知道目前有两种解决方案类型。

• 使用HAL+JSON，你可以使用IANA链接关系描述链接的作用，并使用供应商特定的MIME类型描述字段的模式。
• 使用JSON-LD（或任何其他RDF格式）和Hydra词汇表，您可以根据链接调用的操作发送回RDF元数据。此元数据可以包含字段的验证详细信息（xsd词汇表）和字段的语义（microdata、微格式等）。这些信息与API实现完全解耦，因此可能比使用供应商特定的MIME类型更好，但Hydra仍在开发中，而HAL则更简单。

然而，您的解决方案也是有效的。我认为您应该检查这两个解决方案，因为它们已经成为标准解决方案，REST的统一接口/自描述信息约束鼓励使用现有标准而不是自定义解决方案。但是如果您想创建自己的标准，那就由您决定。

- inf3rno

Answer 3

使用RFC 6861，您可以使用create-form和edit-form链接关系将表单链接到您的表单，而不是客户端自己构建表单。相应的表单应该具有必要的模式来构建POST请求。

- June Oh

Answer 4

我想你在询问有关 Rest API 元数据处理的问题。与 SOAP 不同，Rest API 通常不使用元数据，但是一旦您的 API 大小变大，它有时会非常有用。

我认为你应该看看 swagger。这是你可以找到的最优雅的 Rest API 工具。我已经使用它一段时间了，带有注释支持，使用起来相当容易。它还有许多在 github 上找到的示例。另一个优点是，它包含了漂亮可配置的 ui。

除此之外，你还可以找到其他方法，如 WADL 和 WSDL 2.0。虽然我没有使用过它们，但你可以在 这里 阅读更多相关信息。

- Maleen Abewardana

---

这基本上就是我所说的REST API不应该做的事情。它不应该需要以某种WSDL或其他格式发布其API元数据，因为此时客户端和服务器已经紧密耦合。API应在交互时提供所有必要的信息。 - richard