0

I am writing a web-service that perform some software installation in a asynchronous way. In one case a manual action is needed in the middle of the installation. Thus I paused the installation and wait for the user to request the application to resume the installation.

Currently we can retrieve the running installations by performing a GET request on /running-install and cancel a installation with a DELETE on /running-install/<id> but I can't find the appropriate method to use to resume a paused installation.
I was thinking of something like a doing PUT on /running-install/<id> with a body containing {"status":"running"} but it does not feel very right to me.
Thank you

cassiomolin
  • 124,154
  • 35
  • 280
  • 359
BlackSponge
  • 3
  • 3
  • Why doesn't it sound good? – cassiomolin Aug 07 '17 at 15:53
  • Well I find it a bit verbose, I was wandering I there isn't another verb that could achieve the same goal without having to provide a body. The main reason for me to think that is that we can not pause the installation, so we can't perform a PUT with `{"status":"paused"}`. If it is the "best" I will end up implementing that but I want to be sure. – BlackSponge Aug 07 '17 at 16:00

2 Answers2

0

If you were implementing this protocol as a sequence of web pages using an html representation, then you would probably use POST here, as you likely don't want clients treating this as a safe interaction.

The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics.

Hard to go wrong with that.

Something to keep in mind is that the resources are integration resources.

You should expect to have many many more resources in your integration domain than you do business objects in your business domain.

So if you are having trouble shoehorning the messages you need into the limited resources you have available, then add more resources.

You can make a case for any of POST, PUT, DELETE being correct depending on how you choose to model the integration protocol.

The truth is, if you are actually doing REST, it's perfectly reasonable to offer multiple integration protocols to achieve the same effect. The hypermedia clients can choose which protocol to follow based on the semantics associated with the links on the bookmark page.

Community
  • 1
  • 1
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • I am not a big fan of POST here, as you say it all depends of the model I choose and I don't think it will fit mine unless I make some big change. But thank you anyway for the detailed answer. – BlackSponge Aug 07 '17 at 16:40
0

Which HTTP method is the most appropriate to resume an asynchronous task?

Semantically you want to replace the state of a given task with a new state. PUT seems to be a reasonable choice for this scenario.

Quoting the RFC 7231:

4.3.4. PUT

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. [...]

Then send a representation of the new state in the request payload:

PUT /api/installation/1/status HTTP/1.1
Host: example.org
Content-Type: application/json

{ "value" : "running" }

A successful operation could, for example, return 204 and an attempt to modify the status with an invalid state could return 409.

Note: This answer may also be helpful.

Community
  • 1
  • 1
cassiomolin
  • 124,154
  • 35
  • 280
  • 359