Hi, currently I’m trying to design an API which allows to remote control a server. This API provides an “Update” API meaning that a client can trigger via this API the download and installation of updates on the server. But often I find myself in thinking in actions like “start download”, “start update”, “abort update”, … so I’m wondering if you can give me some advice on how I can define such kind of API with JSON API without “actions”.
In particular I’m interested in the use-case “Start/Stop download”
So far I’ve defined the following:
Collection /updates
of type updates
with attributes size
, status
and a to-one relationship to downloads
. The status
can be PENDING
, DOWNLOADING
, INSTALLING
, …
Collection /downloads
of type downloads
with attributes progress
, timeremaining
, status
. The status
can be ACTIVE
, PAUSED
, COMPLETED
, …
The downloads
resource object for a given update should be kept until the update has been completed or a client explicitly wants to remove it beforehand (e.g. to make space for other updates…).
The solutions I came up with so far to trigger a download are:
-
Issue a
PATCH /updates/<id>
and updatestatus
toDOWNLOADING
. Upon this state change the server should automatically create adownloads
resource object and add the corresponding relationship to the correspondingupdates
resource object. -
Create a new empty
downloads
resource object viaPOST /downloads
and add this object as relationship viaPOST /updates/<id>/relationships/download
. The server should then automatically update the status of the correspondingupdates
resource object toDOWNLOADING
.
… and aborting an download could be realized for both solutions via a DELETE /downloads/<id>
.
First solution requires only one HTTP request but it’s somehow not very intuitive as the client has to manually modify the status. Also it smells a bit like firing actions via a status attribute and the server has to evaluate if a state change PENDING -> DOWNLOADING
is a valid transition.
Second solution requires two HTTP requests and is also not very intuitive and more error prone as the client has to manually setup the relation ship (i.e. it could happen that the client creates the download resource but fails to setup the relationship…). Btw. is there a way to do this in a single HTTP request?
Do you’ve any better idea or recommendation ?
Thanks a lot in advance!