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:
/updates of type
updates with attributes
status and a to-one relationship to
status can be
/downloads of type
downloads with attributes
status can be
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:
PATCH /updates/<id>and update
DOWNLOADING. Upon this state change the server should automatically create a
downloadsresource object and add the corresponding relationship to the corresponding
Create a new empty
downloadsresource object via
POST /downloadsand add this object as relationship via
POST /updates/<id>/relationships/download. The server should then automatically update the status of the corresponding
updatesresource object to
… and aborting an download could be realized for both solutions via a
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!