问题描述
如果我在某个 URI 上有一个资源,比如 https://api.example.com/things/my-things
并且到目前为止这个资源可能会显示在以下表示中:
- 应用程序/xml
- 应用程序/xhtml+xml
- 文本/xml
- 文本/html
服务器应该如何通知请求 application/xml
、application/xhtml+xml
和 text/xml
的客户端将不再支持它们作为资源的表示?现在不行,所以 406 Not Acceptable 是不够的。
我找到了互联网草案 The Deprecation HTTP Header Field,但它是互联网草案,而不是 RFC,我不确定这是否是规范的有效实现,或者这意味着资源/URI是实际被弃用的那个。
有没有人知道一种权威的方式来表达资源的表示正在被弃用,并且即将结束,但 URI 仍然可以使用不同的表示集?
解决方法
最终,您要通知客户端的信息是 API 或应用程序策略之一。确实没有任何标准方法可以通过 HTTP 传达此信息;至少,不是今天。除非您的客户很精明,否则即使您确实提供了这些信息,他们也可能会忽略它,而您又会回到 406 或 415。
我能想到的最佳标准协商方式是要求客户端首先发送 HEAD
和 Accept
或 Content-Type
,然后服务器响应使用 OK
(如果允许)或适当的 406 或 415。可以使用 HTTP 缓存和/或其他技术来最小化协商次数,但在最坏的情况下,总是有两个请求。
次优方法可以说是通过 API 版本控制强制执行的策略。尽管版本差异仅在于表示,但所有方面都清楚地分开。如果 API 版本 1.0
支持 application/xml
,它应该保持这种状态 - 永远。这提供:
- 为客户提供稳定性和可预测性
- 应该允许您轻松识别旧 API 上的客户端(并可能通知他们)
- 在服务器上保持简单
也有几种方法可以松散地宣传特定 API 版本已被弃用。您可以使用标准标头,例如 pragma
或 warning
,也可以使用 api-deprecated-versions: 1.0,1.1
之类的标头。这种方法仍然需要客户端注意这些响应标头,并且不一定指示 API 何时会从弃用过渡到完全停止使用。大多数成熟的服务器 API 策略会有 6 个月以上的弃用期,但这绝不是硬性规定;你必须确定你的客户。这种方法可以做的是启用客户端拥有的遥测,以检测他们使用的 API(和/或版本)是否已弃用。这应该提醒客户端开发人员确定下一步行动;例如,升级他们的客户端。
根据您的版本控制语义,如果它们甚至存在,您可能可以使用 OPTIONS
实现类似但更优化的方法。 Allow-Content-Type
没有 Allow
的补充,但您当然可以定义一个自定义的。您也可以通过这种方式简单地报告 api-supported-versions
和 api-deprecated-versions
。这将使工具和客户端能够选择或检测适当的端点和/或媒体类型。客户端可能会在每次其应用程序启动时使用这种方法来检测和记录他们使用的端点是否仍然是最新的。
最后的建议可能是通过 OpenAPI(以前称为 Swagger)文档来宣传此信息。这样的文档将指示可用的 URL、参数和媒体类型。客户可以请求适当的文档来确定是否支持他们的 API 和预期的媒体类型。
希望能给你一些想法。首先,您需要定义策略并决定如何传达该策略。然后,您需要教育您的客户如何利用这些信息和功能。如果他们选择不遵守该信息,那么请注意空客 - 他们只会收到 406、415 或其他一些适当的错误响应。
,现在没有权威(规范)的方式来做这件事。
当我第一次试图回答这个问题时,我的脑海里是建议添加一个标题,瞧,这已经被提议了。
你提到的The Deprecation HTTP Header Field似乎成为这种规范的做法。
这也是通知客户的最简单方法,而不会增加其他选项的复杂性。这种通知客户的方式意味着客户可以 100% 期望 API 在弃用期间保持其一贯行为,这通常很关键。
通常,资源、表示和“资源的表示”可能意味着相同或不同的事物,这取决于您与谁交谈。我想说的是,从客户的角度来看,它们是一回事,因此标题是通知弃用情况的合理方法。