我正在围绕一个电子商务网站开发一个 REST API，我的资源之一是一个订单，其中包含诸如制造、ID、状态、发货时间等信息。
我已经为我的 Order 资源定义了一个媒体类型，如下所示：
application/vnd.myapp.order.v1+json
我还定义了另一个资源，即订单状态，如下所示：
application/vnd.myapp.order-status.v1+json
我的问题是关于这些媒体类型的版本控制。既然它们是相关的，那么以同步方式对它们进行版本控制是否有意义？例如，如果订单资源的表示发生变化并且我创建了一个application/vnd.myapp.order.v2+json，那么将订单状态媒体类型的版本也提升到 v2 是否明智？我还想知道是否有关于指南的 RESTful 选项。我确实在网上浏览了一下，并没有真正找到任何关于这里最佳实践的内容，因此我们非常感谢任何建议/意见。
【问题讨论】：
标签： rest media-type
我不认为混合版本和媒体类型是个好主意。
在我看来，你应该按照“分离关注原则”和“单一责任”来区分它。
https://en.wikipedia.org/wiki/Separation_of_concerns
https://en.wikipedia.org/wiki/Single-responsibility_principle
许多团队使用 header/url 进行版本控制： 例如： /api/v1/ /api/v2/ 标头{版本：'v1'} 标头{版本：'v2'}
然后我们可以轻松地将请求映射到我们的需求：
@RequestMapping(value="api/v1/books", consumes="application/json")
@RequestMapping(value="api/v2/books", consumes="application/json")
或
@RequestMapping(value="api/books",headers="version=v1", consumes="application/json")
@RequestMapping(value="api/books",headers="version=v2", consumes="application/json")
【讨论】：
虽然它看起来很有用，但它会违反 SoC，并随着 API 的发展而导致其他问题。
对您的 URL 进行版本控制是更好的选择，因为 URL 是一种完美的方式来表明正在处理的资源类型以及与它处理的数据的关系。 （对我来说，引入自定义标题听起来比自定义版本媒体类型更好）
自定义媒体类型通常应该告诉消费者数据的类型及其编码方案（例如 xml 与 json 与纯文本等），而不是在编码方案时您的字段在版本之间的排列方式字面上没有变化。
通过选择此路径，您将：
【讨论】：