I am trying to design a RESTful (or maybe I should say RESTlike, since I am not designing a fully RESTful API, e.g. not hypertext driven) API as part of a refactoring of an existing "take-a-number" queuing management system.
The basic concepts and workflow are :
A given site (location) can propose several different services, and have several desks. Each desk can provide one or more of the services on the site. (e.g. at a bank, you can have an info desk, desks for common operations such as a deposit, and desks where you can sit to speak to a counselor for more complex things, e.g. open a new account or apply for a mortgage)
Whe he enters the building, a customer prints a ticket by selecting a service on a touch screen. (e.g. "Open a new account"). From now on the ticket is tracked in the server's internal state.
The ticket sits in a queue for a while
The desk operator calls the next customer by clicking a button. The system determines which is the next ticket suitable for the desk (given that not all desks provide the same services)
Once the ticket is called to a desk, there is an event outputed and a display system shows the ticket number along with the desk where the customer should go
Once the customer arrives at the desk, the operator clicks another button so signal the beginning of the actual providing of the service
Once the service has been provided and the customer leaves, the desk operator clicks yet another button, the ticket is archived and the desk becomes free again. Until the operator calls the next ticket.
There is a central server and 2 types of client apps : the ticket distributor terminal, and the desk GUI client.
So in terms of REST resources, one of the main resources is the ticket. First, a new ticket is created (POST), and it is attributed a number. That is easy.
But then I don't know how to model the transitions to the ticket state that are initiated by the desk client, since they are not just updates of the ticket but trigger business logic that is executed on the server and has side-effects not only on the ticket :
- Call next ticket (causes a state change on the server, the ticket is taken from the queue, associated with the desk that called it and marked as "being called")
- Signal the server that the customer has arrived at the desk (causes a state change on the server, the ticket is marked as "being served", still associated with the desk)
- Signal the server that the customer has leaved (causes a change on the server, the ticket is separated from the desk, marked as "served", put into a collection of all the served tickets, and a log entry is written to the DB)
- Signal the server that the customer has not arrived (no show) and the ticket is canceled (causes a change on the server, the ticket is separated from the desk, put into a collection of all the canceled tickets, marked as "not served", and a log entry is written to the DB)
All those operations should be performed in an atomic way too, and synchronously.
They map nicely to "actions", i.e. RPC, and that's the way it was implemented in the previous versions of the system (namely RMI calls). For example, the desk can "call the next ticket" (an action), and he gets back the next matching ticket.
How to model them in a RESTful way ?
Also, is it worth it, or should I simply be a little flexible on the RESTfulness and model them as "actions" or something similar (so basically RPC over HTTP) ?
Thanks for your thoughts !