Reputation: 2850
My api has a job resource which contains a state attribute. The state of a job can be "scheduled", "processing" or "done". The jobs state is determined server-side. When a jobs state is "processing" and ETL process is run server-side.
I want the client to be able to triggering an action like "start" which would set the jobs state to "processing" or trigger a "stop" action which would reset the jobs state to "scheduled".
My question here is how should I handle these "custom" action in REST?
I see two possible approaches:
I could create two new endpoint
POST /job/:id/start
POST /job/:id/stop
.
I could create one endpoint which take an action query-param.
POST /job/:id?action=start
POST /job/:id?action=stop
I'm not sure which is considered more RESTful, if either?
Additional, I'm not sure what the response code should be? I'm guessing one of the following: 200 (OK)
, 202 (Accepted)
, 204 (No content)
but not sure which be best. For example, if the api returned a 200 response should the response body contain the job resource with the updated state? Or, should the api just return 204 no content?
Upvotes: 1
Views: 1830
Reputation: 18153
REST does not care about business logic, only about resources - so the most RESTful approach would be a PUT to /job/:id
where the document sent will contain the new status.
Although technically the "correct" solution (don't tell Roy Fielding) I rather prefer explicit "actions" like /job/:id/start
because it allows my resource to return links to those actions to tell the client if the appropriate action is possible or not (a GET to a "stopped" job would contain a link to start that job for example).
On the basis of HTTP status codes I usually return a 204 when I am not interested in the result although in your case a 200 with the updated resource would be correct - only when you e. g. "start" an already started job a 304 Not Modified would be correct from the view of the client as the state wouldn't have changed.
I would chose 202 Accepted if starting a job has no direct effect on the resource because the job will be e. g. queued and only updated later so that the client knows that an async action has been started.
Upvotes: 1