How can I design a good REST API for actions, like in the following cases?

  • lifecycle
    • start a device
    • stop a device
    • ...
  • conversions
    • convert a file from one format to another

In both cases I would always use the abstraction of ActionRequest, something like:

url: api/device/1/start
method: GET or POST
body: StartRequest object (which properties?)

url: api/conversion/sourceFormat
method: POST
body: ConversionRequest object and file stream

In both cases, anyway, I'm not changing the state of the server in anyway, and if it is ok to use GET requests in case of lifecycle actions, that's not possible for conversions where I need to POST a file.

Any suggestions?

  • Is a REST, aka stateless API compatible with a device state dependent functionality ? – Christophe Feb 7 '17 at 8:49
  • In the lifecycle example, that's a backend service that should forward the start/stop/etc. requests to the devices – fra Feb 7 '17 at 8:55
  • In such cases, I choose not to use REST. Instead I use a messaging pattern where a message is posted to the API to be processed. Example: POST /api/startDevice { ... json data ... }. I suppose it could technically conform to REST with a little hand waving, since it is creating a new message to process on the server, but it's not stereotypical CRUD usage. – Kasey Speakman Feb 7 '17 at 17:38

Probably not GET in these cases, as GET is required to be safe

the client does not request, and does not expect, any state change on the origin server as a result of applying a safe method to a target resource. Likewise, reasonable use of a safe method is not expected to cause any harm, loss of property, or unusual burden on the origin server.

How do you feel about spiders calling your lifecycle start point? or user agents proactively fetching your lifecycle start point just in case it is needed?

I'm not changing the state of the server in anyway

It's less about changing the state of the server than it is about changing the state of the resource.

  • lifecycle
    • start a device
    • stop a device

So these are pretty straight forward; think about how you would do it with a web site? There would probably be some status page for the device, with a hyper link on it saying "To start the device, submit this form". You would follow the link to the form, and it would describe all of the data required to start the device, and you fill out the form and submit it, and TADA, side effects on the device.

REST API's work exactly the same way: you read a representation of a resource, that links to a representation of a different resource describing how you can change the first one. You submit the second document, and behind the scene's the API does the necessary to change the first one.

REST API's are just giant bureaucracies: everything gets done by submitting forms. Need to provide some new service? that's a new form.

  • Thanks for the clarification about changing the state of the resource, you're absolutely right. – fra Feb 10 '17 at 14:30

If you have lifecycle actions that you need to express on top of a REST architecture then maybe have a look at the Sun Cloud API for controlling virtual machines and cloud resources.

Similar to your example with starting and stopping a device, in the Sun Cloud API you can start a VM, stop a VM, etc.

You can borrow some ideas from there. It's a relatively simple API and it's also hypermedia driven.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.