Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

2 Answers 2

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.

share|improve this answer
    
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 '12 at 14:04

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)

share|improve this answer
    
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 '12 at 2:09
    
@jfocht Ok. That works. –  Oleksi Aug 10 '12 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 '12 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 '12 at 14:38

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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