URL parameters in RESTful web services

Question

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?

Answer 1

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)

Answer 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.