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

[Ionys320]

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

At my point, you have two possibilities to bypass this:

1. Create a socket client and store it as a local variable, then use it for the api calls (the same client will always be used, with a single connection) ;
2. Call the functions the socket server usually calls. It's possible to ask the socket server to emit to the connected sockets without needing a client for this (io.emit())

[zwimer]

I'd love to be able to script something to add/remove maintenance issues from the command line using this.