超媒体API：如何正确地编写文档？

Question

问题的核心归结为文档，但可能是我没有正确理解其中的一个或多个方面。如果有，请告诉我：-）

假设我的API中有一个或多或少通用的链接关系(https://example.com/rels/accounts)来链接相关的帐户。确切的意思会随着上下文而改变，对吧？

1. 在我的公告牌（或索引）上，我可能有一个与该关系的链接来浏览所有帐户。
2. 在另一个资源（例如帐户组）上，它可能只链接到属于该组的帐户的特定子集。

这种关系本身似乎不是正确的地方。尤其是当您考虑到该URL的有效负载也可能根据上下文而改变时。在我们的示例中，如果在帐户组上有这种关系，则必须省略accountGroup字段，因为该值是由上下文提供的。

据我所知，我可以（也许应该）为API中的每个资源设置一个配置文件，记录资源本身。这将包括它的属性和可能出现的链接。这是我指定链接的确切含义的地方吗？

按照前面的示例，我是否会为profilehttps://example.com/profiles/account-group记录具有https://example.com/rels/accounts关系的链接链接到属于该组的帐户集合？

如果帐户集合资源具有关系类型https://example.com/rel/create-account的链接，我就麻烦大了，对吗？因为这是只包含某个组的帐户的帐户集合的信息没有编码在配置文件https://example.com/profiles/account-collection中，因此不能包含客户端在向该资源发布时必须省略accountGroup属性的信息。

1. 我认为关系定义应该是弱的，并且不包含任何关于如何与它链接到的资源交互的信息，这是对的吗？
2. 如果是这样，我可以期待从客户机遵循一个链接，然后发现他们可以做什么，基于该资源的配置文件。这似乎是错误的，尤其是对于状态转换。
3. 如果概要文件应该记录客户端可能对链接的资源做什么，我就不能跨API中的多个“跳转”传输上下文，对吗？
4. 我应该使用更多的配置文件和关系吗？https://example.com/profiles/global-accounts和https://example.com/profiles/account-group-accounts.

我想得越多，我肯定要么错过了一个关键的部分，要么它是可以用多种方法解决的东西。正因为如此，我意识到这个问题可能没有100%正确的答案。但也许有人能开导我，让我自己做出取舍？：）

Answer 1

让我们一次一个地总结一下你的观点：

1.基于语境的链接关系意义

将您的问题重新表述为代码上下文：当“getAccounts（）”方法在类Billboard和AccountGroup中的含义不同时，我如何记录它？

客户知道它必须发布一个帐户，它将使用一些媒体类型，它认为适合这项任务。然后，服务器将告诉客户机该格式是否可接受，它还可以给出一个可接受的媒体类型列表作为回报。

3.记录概要文件

如果你所说的配置文件是指媒体类型，那么是的，你应该记录它们。实际上应该只记录媒体类型。

5.问题

>

是的，关系不应定义如何与资源交互。媒体类型实际上可以做到这一点（比如表单定义它必须是一篇文章，等等），但通常不是必须的。

是的，客户机不仅会发现可用的转换（链接），还会发现可用的方法。方法(GET、POST、PUT)总是意味着相同的事情，并且它们不在媒体类型中描述，因为媒体类型只描述表示，而不描述资源。服务器通常在响应中提交所有受支持的方法，或者显式地在对选项的响应中提交。