Document the Socket.io API and try to convert it to a HTTP request

[louislam]

Resolves: #118
Resolves: #1210
Resolves: #1276
Resolves: #2358 (might be debatable)
Resolves: #2553 (might be debatable)
Resolves: #3060
Resolves: #3668

#1834 is staled as I think that the workload of implementing and maintaining both rest api and socket.io api is too heavy for me.

New approach:

• Document the Socket.io API, people can connect to it via other Socket.io clients.
• Since Socket.io client is not available for all programming languages, make an endpoint /api to convert a HTTP request to socket.io request
• Define all possible requests in a JSON file
  • /api can use it to verify the request
  • Generate human readable docs from this json file

Of course, the API is not as beautiful as a REST API, but for me, it is much easier for me to maintain. It should work for most "crud" actions.

[chakflying]

If we do it this way, we would have to be clear on the performance expectations, I suspect having to open a new websocket connection inside the server on every api call would be quite a burden.

[louislam]

If we do it this way, we would have to be clear on the performance expectations, I suspect having to open a new websocket connection inside the server on every api call would be quite a burden.

I am reading socket.io's test, it seems that it is possible to create a socket object without an actual real websocket connection.
https://github.com/socketio/socket.io/blob/main/test/socket.ts

[louislam]

If we do it this way, we would have to be clear on the performance expectations, I suspect having to open a new websocket connection inside the server on every api call would be quite a burden.

I am reading socket.io's test, it seems that it is possible to create a socket object without an actual real websocket connection. https://github.com/socketio/socket.io/blob/main/test/socket.ts

Ah... It isn't what I thought, createClient is not a builtin function and it is actually a websocket connection

https://github.com/socketio/socket.io/blob/b4dc83eb9b85e26f09f25e1b5320fe3f49b521d3/test/support/util.ts#L33C1-L41