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:
- Discover available updates
- Apply desired updates
- 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:
- a device id
- 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?