同时使用 HTTP 和 WebSockets 时的 API 命名约定

Posted 2023-02-16

【中文标题】同时使用 HTTP 和 WebSockets 时的 API 命名约定

【英文标题】：API naming conventions when using both HTTP and WebSockets

【发布时间】：2019-03-13 14:38:16

【问题描述】：

对于类似请求同时使用 HTTP 和 WebSocket 协议的 API，最常见的 URI 命名方法是什么？有什么共同的约定吗？

假设我们有一个返回用户集合的 HTTP 请求：

localhost/users

此请求应返回注册用户列表。 在类似的 WS 请求中，服务器应该打开 WebSocket 通道，并在每次更新列表时（例如添加或删除用户等）通过它向客户端发送用户列表。

WebSocket 请求的 URI 应该是什么样的？

我看到了几个选项：

可能是一样的，localhost/users。区别应该仅在请求标头 (Upgrade: WebSocket) 中。缺点是它可能会令人困惑，因为具有相同 URI 的请求会根据提供的标头返回不同的响应

localhost/users-ws。这对我来说似乎有点难看，因为每次我们对 HTTP 请求有类似的 WS 请求时 API 都会增长

localhost/users/ws。这打破了使用变量扩展 URI 的可能性，例如我们不能再在这里使用localhost/users/id。

将所有 WS 请求存储在公共 ws 域 - localhost/ws/users 下。这也很丑陋，因为我们破坏了 URI 中域的顺序，并且无法将带有 users 域的请求重定向到特定的处理程序

所以目前我看不到没有明显缺点的选项:)

如果有人可以提供任何大型项目的示例，例如 *** 或 GitHub，其中 WS 和 HTTP 一起使用，那将非常有帮助。

【问题讨论】：

你有没有得出任何结论？

【参考方案1】：

我不知道 WebSockets 的任何常见命名约定，但对于 Web API，有一个命名约定以 /api/ 开始路由，例如 api.example.com/api/users。

按照这种做法，可以说example.com/ws/users 可能是一个合适的路线名称。

【讨论】：

在考虑了提到的命名选项之后，我们决定停止使用您提出的约定：/api/path 用于 HTTP 请求，/ws/path 用于 WebSocket 请求。感谢您的回复！