Rest – Mixing REST and websocket in the same API

netrestwebsockets

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.

Best Answer

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.

Related Solutions

Event Sourcing – Integrating Event Sourcing with REST

I think you may have a user-process to implementation mismatch here.

First: will a user honestly want to perform multiple changes to a file simultaneously? A rename (which may or may not include a change of path?), change of ownership, and perhaps change of file contents (for sake of argument) seem like separate actions.

Lets take the case where the answer is "yes" - your users really do want to make these changes simultaneously.

In that case, I'd strongly recommend against any implementation that sends multiple events - RenameFileCommand, MoveFileCommand, ChangeOwnerCommand - to represent this single user intent.

Why? Because events can fail. Maybe its extremely rare, but your user submitted an operation that looked atomic - if a single one of the downstream events fails, then your application state is now invalid.

You are also inviting race hazards on a resource that is clearly shared between each of the event handlers. You will need to write "ChangeOwnerCommand" in such a way that the file name and file path do not matter, because they could be out of date by the time the command is received.

When implementing a non-event driven restful system with moving and renaming files, I prefer to ensure consistency by using something like an eTag system - ensure that the version of the resource being edited is the version that the user last retrieved, and fail if it has been modified since then. But if you are dispatching multiple commands for this single user operation, you will need to increment your resource version after each command - so you have no way to know that the resource the user is editing really is the same version as the resource they last read.

What I mean by that is - what if someone else performs another operation on the file at nearly the same time. The 6 commands could stack up in any order. If we had just 2 atomic commands, the earlier command could succeed and the later command could fail "resource has been modified since it was last retrieved". But there is no protection against this when the commands are not atomic, so system consistency is violated.

Interestingly there is a movement toward something like event based architecture in REST, called "Rest without PUT", recommended in the Thoughtworks technology radar, Jan 2015. There is a considerably longer blog about Rest without PUT here.

Essentially, the idea is that POST, PUT, DELETE and GET are fine for small applications, but when you need to start assuming how put and post and delete might be interpreted at the other end, you introduce coupling. (e.g. "when I DELETE the resource associated with my bank account, the account should be closed") And the solution proposed is to treat REST in a more Event sourced way. i.e. Lets POST the user intent as a single event resource.

The other case is simpler. If your users don't want to do all those operations simultaneously, don't let them. POST an event for each user intent. Now you can use etag versioning on your resources.

As for the other applications which are using a very different API to your resources. That smells like trouble. Can you construct a facade of the old API on top of your RESTful API and point them at the facade? i.e. expose a service that performs multiple updates to a file in sequence via the REST server?

If you neither build the RESTful interface on top of the old solution, nor build a facade of the old interface on top of the REST solution, and attempt to maintain both APIs pointing at a shared data resource, you will experience major headaches.

DDD Application Services vs REST API – Conceptual Mismatch

I've had the same problem and "solved" it by modelling REST resources differently, e.g.:

/users/1  (contains basic user attributes) 
/users/1/email 
/users/1/activation 
/users/1/address

So I've basically split the larger, complex resource into several smaller ones. Each of these contain somewhat cohesive group of attributes of the original resource which is expected to be processed together.

Each operation on these resources is atomic, even though it may be implemented using several service methods - at least in Spring/Java EE it's not a problem to create larger transaction from several methods which were originally intended to have their own transaction (using REQUIRED transaction propagation). You often still need to do extra validation for this special resource, but it's still quite manageable since the attributes are (supposed to be) cohesive.

This is also good for HATEOAS approach, because your more fine-grained resources convey more information on what you can do with them (instead of having this logic on both client and server because it can't be easily represented in resources).

It's not perfect of course - if UIs is not modelled with these resources in mind (especially data-oriented UIs), it can create some problems - e.g. UI presents big form of all attributes of given resources (and its subresources) and allows you to edit them all and save them at once - this creates illusion of atomicity even though client must call several resource operations (which are themselves atomic but the whole sequence is not atomic).

Also, this split of resources is sometimes not easy or obvious. I do this mainly on resources with complex behaviors/life cycles to manage its complexity.

Best Answer

Related Solutions

Event Sourcing – Integrating Event Sourcing with REST

DDD Application Services vs REST API – Conceptual Mismatch

Related Topic