如果没有文档，您如何知道将数据发布到基于rest的api的格式？
集合的get应该返回一个示例元素吗？
我猜我在想HATEOAS，GET调用返回POST的链接，但是您怎么知道POST的格式？
https://martinfowler.com/articles/richardsonMaturityModel.html
答案 0 :(得分：1)
OpenAPI standard是提供标准的，可发现的信息和有关API所有输入/输出格式的示例的好方法。它实质上是具有支持基础结构（Swagger）的类似REST的API格式的YAML规范的标准，该规范可以轻松地将该规范转换为人类可读的文档，有效的输入和输出数据示例以及样板许多编程语言和框架中的代码将向已记录的API发送数据或从已记录的API发送数据。
要开始使用，Swagger page或editor hands-on demo可能会很有趣。
答案 1 :(得分：1)
如果没有文档，您如何知道将数据发布到基于rest的api的格式？
服务器应告知客户端请求的外观。在HTML中，即通过包含服务器支持的所有元素的Web表单来完成。在更新的情况下，字段可以自动填充可以由用户/应用程序修改的当前值。由于表单还包含将数据发送到的URI，因此客户端只需调用表单的Submit按钮即可触发请求。
对于REST API，可以并且应该采用类似的方法。在这里，服务器可能会向客户端提示所支持的媒体类型（取决于客户端接收的媒体类型是否支持这种功能），也可以通过通知客户端的OPTIONS操作来查找该提示。有关端点功能的信息，例如可以在端点上调用的受支持的媒体类型或操作。
集合的get应该返回一个示例元素吗？
如果为客户提供了说明请求外观的表格，则此处实际上不需要带外信息，因此这是不必要的。
当您链接了Richardsen成熟度模型（RMM）：IMO时，此模型在REST方面意义不大。首先，无论如何，在第3级之前都没有REST依从性，即使采用第3级，也不能保证您确实符合REST体系结构设计。
我想这可能需要进一步解释。 REST是一种交互模型，而不是协议。它利用了使Web如此成功的属性，例如通过无状态通信轻松进行缩放，以及由于在中间服务器上缓存响应或在负载平衡的服务器之间分配请求而减少了工作量。它的目标之一是使客户端和服务器脱钩，使后者和服务器可以自由发展，而不必担心破坏前者。这样一来，服务器应该教客户什么需要做的明智选择，以便下一步可以执行哪些“动作”。
即，服务器将提供客户端可能需要的所有链接，包括一些随附的链接关系名称，其中关系名称为URI提供了一个命名上下文，客户端可以使用该上下文来决定是否调用它。这样的名称要么由IANA标准化，要么需要是RFC 8288 - Web Linking中定义的绝对URI，即Dublin Core扩展名。此概念允许服务器随时更改资源的URI。尊重这一概念的客户仍然能够处理其任务，而客户解析和分析此类URI可能因此而中断。
根据Fielding
REST API应该花费几乎所有的描述性精力来定义用于表示资源和驱动应用程序状态的媒体类型，或者为现有标准媒体定义扩展关系名称和/或启用超文本的标记类型。花费所有精力描述应该在媒体类型的处理规则范围内（并且在大多数情况下已由现有媒体类型定义）完全定义要在感兴趣的URI上使用的方法，{Source）< / p>
除此之外，菲尔丁提到客户不应该考虑resources to have a certain type，而应该通过内容类型协商与服务器协商两个应用程序都理解的受支持的表示格式。如果响应随其他字段名或其他值类型一起发送，或者通常带有与预期不同的其他结构，则期望http://acmee.com/api/users端点返回具有预定义字段的JSON表示形式的客户端可能会遇到某些问题。这也将客户端直接耦合到某个API的返回值，因此需要一定的带外知识。这就是RMM中完全缺少的东西。因此，即使您已达到RMM的第3级，您仍然可能无法遵守Fielding为遵守REST体系结构样式而施加的所有约束。