如果没有文档，您如何知道将数据发布到基于休息的api的格式？
集合的get应该返回一个示例元素吗？
我想我在想HATEOAS，GET调用返回到POST的链接，但是你怎么知道POST的格式？
https://martinfowler.com/articles/richardsonMaturityModel.html
如果没有文档，您如何知道将数据发布到基于休息的api的格式？
服务器应该教客户端请求应该是什么样子。在HTML中，即，这是通过包含服务器支持的所有元素的Web表单完成的。在更新的情况下，字段可以自动填充可以由用户/应用程序修改的当前值。由于表单还包含用于发送数据的URI，因此客户端只需通过调用表单的提交按钮来触发请求。
对于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可能会因此而中断。
据菲尔丁说
REST API应该花费几乎所有的描述性工作来定义用于表示资源和驱动应用程序状态的媒体类型，或者为现有标准媒体类型定义扩展关系名称和/或启用超文本的标记。在媒体类型的处理规则范围内（并且在大多数情况下，已经由现有媒体类型定义）应该完全定义用于描述在感兴趣的URI上使用哪些方法的任何努力（Source）
除此之外，Fielding提到客户不应该考虑resources to have a certain type，而是通过内容类型协商与服务器协商两个应用程序理解的支持的表示格式。期望http://acmee.com/api/users端点返回具有预定义字段的JSON表示的客户端如果响应随其他字段名称或其他值类型一起提供或者通常具有除预期之外的其他结构，则可能存在某些问题。这也将客户端直接耦合到某个API的返回值，因此需要某些带外知识。这就是RMM中完全缺失的东西。因此，即使您在RMM中达到级别3，您仍可能无法遵守Fielding为遵守REST架构风格而制定的所有约束。
OpenAPI standard是一种提供关于API的所有输入/输出格式的标准化，可发现信息和示例的好方法。它本质上是类似REST的API格式的YAML规范的标准，具有支持基础结构（Swagger），允许将该规范轻松转换为人类可读的文档，输入和输出数据的有效示例，以及许多编程中的样板代码将数据发送到文档化API或从文档化API发送数据的语言和框架。
要开始，Swagger page或editor hands-on demo可能很有趣。