Mixing REST and websocket in the same API

Question

A bit of background first, I'm working on an application that manages a piece of physical equipment with motors, stuff like that. When I started on the project, there was an existing application, built with Labview and that was in a poor state. The part of the code that manages the hardware, the "drivers" were in a better shape. The goal was to write a new app, in .Net, but reusing as much as possible the existing drivers.

The architecture that was decided was to separate strongly the hardware side, written in Labview, and the management/data treatment side written in C# through the use of a REST web service, since Labview has a relatively good support of them. The Labview hardware part has the role of the server, and the .Net side connects through it, asks for status of the hardware and sends command to move the hardware and so on.

In so far, it works pretty well, the only annoying part is the amount of polling that is needed from the client side. We have some "long commands", for which we send a command that asks the hardware to do a long operation, but we want to have some updates on how it goes. For this, we send the PUT to initiate the action and then, every 500 ms (or slower depending on the action), we send a GET to have the current status of the action, until the action is done (usually defined by a flag).

When I started with the project, a few months ago, I had seen this issue and did some research to see if there was a solution to this problem, like a way to use SignalR for Labview, and didn't find anything. But now, we have found an implementation of a WebSocket server in Labview. I'm now wondering if and how this could be implemented in (or as a replacement of) our solution.

One of the solution I was envisioning was to keep the REST service for most, but create on the fly a WebSocket endpoint for those few long-lasting commands that need updating. For example, send a PUT command to do an action, for which the server would start the action, return the 200 OK and add the address of a WebSocket endpoint where the client could go to get status. As soon as the client connects to the WebSocket, the server would send updates through this. When the action is done, connection is closed, and WebSocket endpoint is closed on the server side.

I've searched a bit to see if someone were doing that kind of "mixed" service, but cannot find anything, so I'm wondering if it's really a good idea. Even though I'm not a huge fan of the amount of polling that happens now, I also really like the REST API that we have created and feel like it would be a bit of a loss to scrap it and go the WebSocket way completely. I think WebSocket is still not as universal as REST (even in .Net 4.5, the ClientWebSocket class is useable only in Windows 8, even though alternatives exists). Using WebSocket also means defining our own communication protocol (how to define commands, etc.) which can be difficult.

In a way, mixing doesn't seem completely "right" either, because I'm not going to use completely the "full-duplex" advantage of WebSocket, mostly using them for communicating back information from the server to the client in a sort of "push" way, rarely sending commands from the client to the server through the web socket.

Answer 1

It's all about discovery: the ability of your API to be understandable and usable by the next developer encountering it. If the WebSocket methods are easily discoverable, and it is clear that they should be used in conjunction with the ordinary REST methods, then your design is probably sound.

In practice, for this discovery to occur, I think your WebSocket methods need to be defined in close proximity with your ordinary REST methods, along with some clarifying comments suggesting their proper use and coordination.

If the WebSocket methods are meant to be used independently of the REST interface, then you can put them in their own API.

Answer 2

I am not familiar with your tech stack, but I have built a web app combining REST and websockets.

In my case I made a few decisions:

• Ensure my REST API was complete with respect being able to retrieve all information that was also provided via the websocket.
• Set an upper limit on how long my REST calls can take - basically they can do database updates and can manipulate the state of long running processes (start/stop etc) - they never wait for long running processes to complete.
• The Websocket is "almost" one way - it publishes events happening on the back end. However it is necessary to register for events via the websocket.
• The client is expected to avoid polling by registering for events.
• However it is acceptable for a new client to check the current state of an already running process when they first connect via a REST call, in this case I typically register for events first, before making the REST call.

This application doesn't have particular high performance requirements, so my goals were just to keep things simple and not write too much duplicate code between REST and websockets:

• All commands to the server are via REST.
• Any query that can be answered immediately is also made via REST.
• All long running / async processes use event notifications via the WebSocket.

Implementation

My app is an internal application so I use STOMP over websockets. Hence there is little I have to do on the server side. When an event occurs I use the same model objects I use for the REST API and just push them on to the relevant queues.

The front end does a stomp registration to the relevant queue(s).