REST API - 客户端如何知道POST到资源的有效负载是什么？

Question

REST API架构的目标之一是将客户端和服务器分离。

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

不知何故，API需要向UI传达给定资源的POST方法的有效负载。否则，我们将依赖于使用API​​所需的带外知识，我们再次紧密耦合。

所以我有这样的想法，即资源上的GET的API响应将提供用于为该资源上的POST方法构造有效负载的规范。这将包括字段名称，数据类型，最大长度等。

This guy has a similar idea

处理此问题的正确方法是什么？大多数人只是依赖于带外信息吗？在这个问题上，人们在现实世界中做了什么？

修改

以下序列图说明了解决此问题的方法：

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

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

以下是发生的事情：

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

没有魔法/元资源，不需要使用元数据的方法。一切都由API提供。

思想？

Answer 1

大多数人都依赖于带外信息。但这通常没问题，因为大多数客户端不是动态构建的，而是静态构建的。它们依赖于API的已知部分而不是HATEOAS驱动。

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

Answer 2

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

我知道有关此的2种当前解决方案类型：

• by HAL+JSON您使用IANA link relations来描述链接的作用，以及供应商特定的MIME类型来描述字段的架构
• 通过JSON-LD（或任何其他RDF格式）与Hydra vocab根据链接调用的操作发送回RDF元数据。这个元数据可以包含字段的验证细节（xsd vocab）和字段的语义（微数据，微格式等等）。这些信息与API实现完全分离，因此它可能比使用特定于供应商的MIME类型更好，但Hydra仍在开发中，HAL更简单。

然而，您的解决方案也是有效的，我认为您应该检查这两者，因为它们已经是标准解决方案，REST的uniform interface / self-descripting message constraint鼓励使用现有标准而不是自定义解决方案。但是如果你想创建一个自己的标准，这取决于你。

Answer 3

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

我认为你应该研究swagger。这是最优雅的你可以找到休息apis。我已经使用它一段时间了，并且通过注释支持它很容易使用。在github上也有很多例子。其他优点是，它包含很好的可配置ui。

除此之外，您还可以找到其他方式，例如WADL和WSDL 2.0。即使我没有使用它们，你也可以阅读更多关于它们here。

Answer 4

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