如何为RESTful Web服务创建自定义媒体类型（application/vnd）？

Question

我现在正在使用REST，想要正确实现HATEOAS以弄清楚所有概念。

为此，我想创建自己的媒体类型 (application/vnd[...]+xml 和 application/vnd[...]+json)。

首先一个问题: 媒体类型是否定义了我的服务器和客户端之间的合同？

媒体类型将定义我的消息格式，因此我需要添加 XML 模式和 JSON 模式来配合新的媒体类型 (这样 REST 客户端就知道消息内容和如何响应)。

我在网上做了一些研究，但是如何做到这一点的详细信息却不见了。它只涉及编写详尽的规范/文档或者还有一些技术步骤需要实现吗? (我需要向 IANA 注册吗?)

如何创建一个新的 - 完全功能的 - application/vnd 媒体类型? 你需要注意什么，以便客户端可以正确地使用它?

- JohnDoDo

---

对于其他路过的人：RESTful Web APIs 这本书是一本非常棒的书籍，如果你对正确实现 REST 感兴趣，那么这本书绝对是必读之选。 - Torben Koch Pløen

Answer 1

@JohnDoDo

首先问题是：媒体类型是否定义了我的服务器和客户端之间的契约？

是的，媒体类型是合同的一部分。在REST API中，合同不像SOAP（即WSDL）那样是静态的。合同由底层协议（即HTTP）、URI和媒体类型的组合定义（不禁止同时使用多个媒体类型）。媒体类型定义数据模型、处理模型、超媒体控件（例如注释链接、输入表单等）和支持包括由链接关系、元素名称、ID、类名等描述的附加应用特定信息。

媒体类型将定义我的消息格式，因此我需要添加XML模式和JSON模式以配合新的媒体类型（以便REST客户端知道消息内容并返回什么）。

您只需要定义覆盖文档结构的通用模式。您不需要为特定消息定义单独的模式。您的消息必须符合媒体类型定义的结构。

如何创建一个新的完全功能的application/vnd媒体类型？并且要注意哪些问题，以便客户端可以正确地使用它？

1. 描述它（编写格式规范）；
2. 向IANA注册：http://www.iana.org/cgi-bin/mediatypes.pl在vnd.* 树下注册媒体类型需要近一周的时间。

- ioseb

---

非常感谢！所以说，归根结底，只需要一个扎实的书面规范，对吗？ - JohnDoDo

关于第二点的澄清：建议进行注册，但这不是强制要求。请参见https://dev59.com/vF4b5IYBdhLWcg3wchTs。 - Wim Deblauwe

Answer 2

请看：

请查看三步实现RESTful超媒体API

您的媒体类型应该描述数据类型，但我不建议使用XML模式。如果您使用XML模式，我强烈建议您使用松散版本控制策略，否则每次添加新元素或属性时都需要一个新的媒体类型。

- Tom Howard

---

所以如果我理解正确：只需要有一个良好的文档描述媒体类型，这样开发人员就知道如何编写客户端代码了？ - JohnDoDo

正确的做法是抵制优化的冲动，让客户端直接访问特定的URL。客户端从众所周知的根URI（例如http://www.example.org/list/）开始，只需跟随链接和表单即可到达所需位置。例如，GET http://www.example.org/list/ 告诉我可以在http://www.example.org/list/?open获取未完成的项目。开发人员很容易将其嵌入客户端，但明天GET http://www.example.org/list/可能会告诉我们未完成的项目位于GET http://www.example.org/openlist或甚至http://www.otherexample.org/list/。 - Tom Howard

我需要提醒你的是，你应该尽量减少在你的媒体类型文件中传递的带外信息，并最大化客户端可以从响应中接收的带内信息。客户端依赖于越多的带外信息，它们与你的服务器之间的联系就会更加紧密，这会使得你的服务器难以升级。 - Tom Howard

你所说的越界信息是指未定义URL格式和位置，还是限制消息内容的信息？（例如，您建议在答案中不添加XML / JSON模式）。这是我阅读过的资源中的另一个问题。我理解导航不应该是客户端的优先信息，但是消息内容呢？客户端需要优先了解消息内容以发送/接收，否则它将不知道如何处理消息。正确吗？或者我漏掉了什么？ - JohnDoDo

就您的客户收到的响应而言，是的，它会期望某种响应；但是，如果响应中有额外的信息，客户不应该在意。就您发送的请求而言，这应该仅由您接收到的响应中的链接和表单来确定。 - Tom Howard

Answer 3

“媒体类型是否定义了我的服务器和客户端之间的协议？” 不是的，媒体类型只定义了数据的类型（例如应用程序）和子类型（例如json）。

“如何创建一个新的完全功能的application/vnd媒体类型？需要注意什么才能让客户端正确使用它？” 如果您决定创建自己的自定义媒体子类型，并希望它被广泛使用，那么应该将其注册到IANA（http://www.iana.org/assignments/media-types）。这是与潜在客户共享带外信息的标准方式。

- subodh