3

I'm wondering about the appropriateness of URL parameters in RESTful resource creation.

First, here's some context. I'm working on an API that will remotely update the software on embedded devices connected to an online device cloud. The basic workflow is:

  1. Discover available updates
  2. Apply desired updates
  3. Monitor update progress

The update discovery resource will allow users to POST a new update discovery.

POST /updateDiscovery?apikey=a1b2c3

The above URL will trigger update discovery for all devices. It is also useful to restrict which devices are targeted for updates. There are two identifiers used to restrict target devices:

  1. a device id
  2. a group id (which may reference many devices)

This restriction can be communicated using either URL parameters or the request body.

Using URL parameters:

POST /updateDiscovery?deviceIds=1,2,3&groupIds=2,3

Using the request body:

POST /updateDiscovery
Content-Type: application/json
{
    targets: {
         deviceIds: [1, 2, 3],
         groupIds: [3, 4]
     }
}

Either way, a new resource will be created with the following representation:

{ 
   id: 1,
   targets: {
        deviceIds: [1, 2, 3],
        groupIds: [3, 4]
   },
   status: 'pending',
   ...
}

Which of the above methods best follows the RESTful design pattern and why?

2 Answers 2

2

There is no problem with using parameters in RESTful API calls, however you want all the calls to be on resources. Right now you have \updateDiscovery which corresponds to an action, not a resource. An update is a resource though, so I would try designing it in terms of that (\updates)

4
  • Ok, helpful. I would argue that update discovery does correspond to a resource. The update discovery resource describes the status and result of an update discovery job. The API also has update resources which describe the status and result of applying specific updates.
    – jfocht
    Aug 10, 2012 at 2:09
  • @jfocht Ok. That works.
    – Oleksi
    Aug 10, 2012 at 2:11
  • There is no problem with using parameters - can you comment on which you would actually use in the above scenario?
    – wal
    Aug 10, 2012 at 10:38
  • I would prefer \updateDiscovery?deviceIds=1,2,3&groupIds=2,3 over sending it in the body, because it makes it (marginally) easier to look at and test. Really it's just a matter of preference.
    – Oleksi
    Aug 10, 2012 at 14:38
0

This "updateDiscovery" entity seems a bit too abstract to me. I would rather have a clear separation between "devices" and "updates". This way I could call GET on "/devices/{deviceId}/updates", to get a list of all updates which have been applied to a device. Or GET on "/updates?deviceIds=..." to get a list of updates that should be applied to specified devices.

1
  • It is a little bit abstract, but it's named that for a reason. The updateDiscovery job will trigger a discovery of available updates for up to 10,000 devices across many different transports (ethernet, cell, satellite). This job may take a long time, so it doesn't really make sense for the request to be a get.
    – jfocht
    Aug 10, 2012 at 14:04

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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