自定义媒体类型的使用是一个不错的选择吗？

Question

我被一位开发人员(现在左)说服了,发展RESTful Web服务的正确方法是为您的服务创建自定义媒体类型.

例如application/vnd.acme.payroll.v1 + json

这样,您可以告诉客户端指定要使用的编码而不更改URI.

这种技术是好的吗？通常服务将版本嵌入到URL中:

例如/acme/1.0/payroll/

我在执行客户端使用此方案时遇到了很多困难,特别是因为DELETE似乎没有强制执行媒体类型

Answer 1

您可以在RESTful服务中使用一些主要的信令机制:

• 媒体类型
• 将rel要链接到的资源.
• 自定义标题,例如Accept-Version/ Api-Version.

每个都有不同的用途,我将概述在设计API时我们理解它们的方式.

媒体类型

为了表明给定资源上可能的操作,以及这些操作的语义,许多人使用自定义媒体类型.在我看来,这不太正确,而且rel更准确.

自定义媒体类型应该告诉您数据的类型,例如其格式或某些信息的体现或嵌入方式.拥有自定义媒体类型意味着您的API的消费者与该特定表示紧密耦合.然而,使用更通用的东西,比如说application/json"这只是JSON数据".

通常单独使用JSON对于RESTful服务是不够的,因为它没有内置链接或资源嵌入功能.这就是像HAL(application/hal+json)这样的东西.它是JSON的一种特殊化,它仍然是一种通用格式,而不是特定于应用程序的.但它足以覆盖链接和嵌入语义在JSON之上,这是连贯表达RESTful API所必需的.

链接关系类型(relS)

这将我们带到了rel.对我来说,自定义rel是表示正在处理或链接的资源类型的完美方式.例如,rel用户资源的自定义可能是http://rel.myapi.com/user,它有两个目的:

• 您的API的客户端必须提前知道此密钥,因为它是特定于API的知识.例如,如果它在您的初始资源上可用并且您使用HAL链接到用户资源,则客户端可能会找到用户链接initialResource._links["http://rel.myapi.com/user"].href.
• 编写 API客户端的开发人员可以在其Web浏览器中访问该URI,并获得该资源在API中表示的内容的说明,包括适用的方法和操作方法.这是一种非常方便的方式来传达我提到的API特定知识.有关此示例,请参阅http://rel.nkstdy.co.

如果将rels与标准或半标准媒体类型组合在一起application/hal+json,则会获得遵循其媒体类型指定的统一格式的资源,并使用由其定义的API特定语义rel.这几乎可以让你一路走来.

自定义标题

剩下的问题是版本控制.如何让客户端协商不同版本的资源,同时不使旧URI失效？

我们的解决方案受Restify Node.js框架的启发,是两个自定义标头:Accept-Version来自客户端,X-Api-Version与服务器(或Api-Version即将发布的Restify 2.0版本,根据新的RFC 6648)非常匹配.如果它们不匹配,400 Bad Request则结果为a.

我承认自定义媒体类型在这里是一个相当流行的解决方案.在我看来,根据上述考虑,它们在概念上并不合适,但如果你选择它们作为你的版本控制机制,你就不会做一些奇怪的事情.当GET你注意到它与其他方法一起使用时,它会有一些语义问题.

要记住的一件事是,在真正的RESTful系统中,版本控制不应该是这样的问题.它应该只在一个非常具体的情况下:当资源的表示以向后不兼容的方式改变时,你仍然希望保持相同的rels.因此,如果http://rel.myapi.com/friend资源突然失去其username领域并获得一个id领域,那将是合格的.但是如果它突然获得了一个nickname字段,那就不是后向不兼容的,所以不需要进行版本控制.如果"朋友"的概念在您的API中完全被替换为"连接"的概念,那么这实际上并不是向后兼容的,因为API消费者将不再http://rel.myapi.com/friend在API中的任何位置找到链接以供他们遵循.