json - API 设计 : HATEOAS, json、版本控制和媒体类型

Question

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

似乎最佳实践是使用供应商媒体类型，如application/vnd.me.v1+json，但是所有这些都在谈论 JSON 中的超链接没有格式，像 HAL、JSON+Collection 和 Siren 这样的东西都有自己的媒体类型。

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

并且，如果必须将其定义为媒体类型，那么这样的操作有效吗？

application/vnd.me.v1.hal+json

有人吗？

Answer 1

First, why specify a format through media type?

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

application/vnd.me.v1.hal+json

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

This is a good SO post考虑媒体类型: