如何通知 REST API 客户端进行可选/必需更新？

Question

我目前正在开发一个 Restful API，我想知道最优雅、最长寿的解决方案是什么。

一些数据：

• Rest API：服务器后端
• 应用：移动应用（ios、android等）

两者都由我们管理和使用。

这是我的要求：

1. 更新是可选的，但推荐，我们只是想通知客户更新他的应用程序。

2. 需要更新，API 不再可用（由于 api 版本控制，这绝不应该发生，但谁知道）

我能想到几个解决方案：

• 包括一个新的 HTTP 标头，例如：

X-Client-Update: text="Some informative and meaningful message"; button="Do upgrade now!"; uri="itms-apps://itunes.com/apps/DevelopmentCompanyLLC"

应用程序将负责处理它并将其显示给用户。

• 提供端点：

请求：

POST /api/versions/
Content-Type: application/json
{"client_version": "4.3", "os_version": "6.0", "os_vendor": "ios"}

响应（可用更新）：

{
    "current_version": "4.4", 
    "latest_compatible_version": "4.0",
    "update_required": false,
    "update_available": true,
    "message": "A new awesome update is available, download it now",
    "uri": "itms-apps://itunes.com/apps/DevelopmentCompanyLLC",
    "button_text": "I want it, and I want it now!"
}

响应（无可用更新）：

{
    "current_version": "4.3", 
    "latest_compatible_version": "4.0",
    "update_required": false,
    "update_available": false,
}

如果需要更新应用程序，我还希望始终返回将由应用程序处理的错误。

我想知道应该使用哪种 HTTP 状态，现在我想到了400 Bad parameters，因为我找不到更好的代码。

相应的消息将与端点解决方案提供的消息非常相似。

Answer 1

由于服务器和客户端都是由您开发的，因此使用哪个状态码并不重要（恕我直言）。除了您选择的400，您还可以查看以下状态码：

• 403 Forbidden - 如果服务器理解请求但拒绝执行它，则适用；服务器应在实体中描述拒绝的原因。
• 501 未实现 - 如果服务器不支持 [不再] 满足请求所需的功能，则适用。

正如您所写，必需的更新永远不会正常发生，因此可选更新是主要用例，后者的条件响应似乎适合任何成功的请求。在这种情况下，您应该像往常一样使用200 状态码，并依赖响应中的附加标头。