API 设计：HATEOAS、json、版本控制和媒体类型答案

【问题标题】：API design: HATEOAS, json, versioning, and media typesAPI 设计：HATEOAS、json、版本控制和媒体类型
【发布时间】：2012-12-19 10:39:33
【问题描述】：

我喜欢 REST HATEOAS 的概念，即通过超链接让您的 API 可被发现。人们喜欢使用 ATOM 格式的 XML 链接，您甚至可能不需要对 API 进行版本控制。但是，我只在做 JSON，我想对我的 API 进行版本控制，并且仍然做 HATEOAS。

似乎最好的做法是使用application/vnd.me.v1+json 中的供应商媒体类型，但是所有这些都在讨论 JSON 中的超链接没有格式以及 HAL、JSON+Colleton 和 Siren 等具有它们的东西自己的媒体类型。

所以，这是我的困惑。首先，为什么要通过媒体类型指定格式？为什么在 JSON 中包含链接不能只是客户遵循的约定？ hm-json浏览器不就是这样发现链接的吗？

而且，如果必须将其定义为媒体类型，这样的方法是否可行？

application/vnd.me.v1.hal+json

有人吗？

【问题讨论】：

【解决方案1】：

首先，为什么要通过媒体类型指定格式？

是的，您可以对链接的格式有一个约定，但是，只有在解压 HTTP 消息的正文后才能发现任何约定。由于媒体类型是标头，因此消息的主体可以作为一个整体被接受或拒绝。对于不支持所提供的媒体类型的消费者，这使得处理请求的效率更高。

应用程序/vnd.me.v1.hal+json

据我了解，媒体类型可以限定为适合您所描述的 API 的级别。因此，您可以选择为单个表示、一组都遵循相同服务的表示或整个组织的单一媒体类型。

【讨论】：

谢谢，您的解释和链接很有见地。关于第二个问题，如果客户端理解 HAL 并将 application/hal+json 视为媒体类型，它可以自动发现链接，但当媒体类型为 application/vnd.me 时，同一客户端是否会理解并自动发现 HAL 格式的链接。 v1.hal+json?
我可能是错的，但我不这么认为。 IANA 文档并支持标准媒体类型。所以，我希望这些会得到支持，但在 HTTP 规范中，它似乎并没有表明消费者可以自动理解的媒体类型（除了类型/格式）有一种特殊的格式。
现在我很困惑。那么，那么 hal+json 对媒体类型有什么意义呢？
This blog post 看起来很有帮助。