API naming conventions when using both HTTP and WebSockets

Question

What is the most common approach to URI naming for API which uses both HTTP and WebSocket protocols for similar requests? Are there any common conventions for that?

Lets suppose we have a HTTP request returning the collection of users:

localhost/users

This request should return a list of registered users. On similar WS request, the server should open WebSocket channel and send a list of users to the client over it every time the list is updated (e.g. user was added or removed, etc).

How should the URI for WebSocket request look like?

I see several options:

1. It may be the same, localhost/users. The difference should be only in the request headers (Upgrade: WebSocket). The drawback is that it can be confusing as requests with same URI return different responses dependent on provided headers

2. localhost/users-ws. This seems a little bit ugly for me as the API grows each time we have similar WS request for a HTTP request

3. localhost/users/ws. This breaks the possibility of extending the URI with variable, for example we can't use localhost/users/{id} here no more.

4. Store all WS requests under common ws domain - localhost/ws/users. This is also ugly as we break the order of domains in the URI and can't redirect requests with users domain to the specific handler

So at the monent I don't see an option without obvious drawbacks:)

If someone can provide any examples of big projects like StackOverflow or GitHub where WS and HTTP are used together, it will be very helpful.

Answer 1

I am not aware of any common naming conventions for WebSockets but for web APIs there is a naming convention to start the route with /api/, example api.example.com/api/users.

Following that practice, it could be argued that example.com/ws/users could be a fitting route name to use.