REST API endpoint to request all available data from a resource

Question

I am developing a REST API where users can request data from one or more sensors, using the following scheme:

GET /sensors - returns a list of available sensors
GET /sensors/<sensor_ids>/data - returns data for one or more sensors, specified by sensor_ids

But the client also wants users to be able to send a request without a sensor_id, which will return all available data for all sensors.

I was thinking there are two ways we could do this:

1. GET /sensors/all/data - specify sensor_id as "all"
2. GET /sensors/data - omit the sensor_id altogether

I am not sure which would be the better option and most consistent with REST best practices. Data and sensors are both resources, but data is always associated with a sensor.

Any suggestions would be appreciated.

• Ian Jacobs: Not knowing anything about the domain. 'All' is a dangerous concept when it comes to sending data over the wire. Consider baking in paging or some other mechanism for if/when all data in 1 call isn't feasible from a performance perspective.

Answer 1

It seems a bit weird to me that sensor ID is a part of resource path yet you mention one or more IDs.

I'd like to think of a single resource /sensors/data. Sensor IDs can be considered as optional filters of all sensor data, passed through query parameters. You might have:

• GET /sensors/data – return data for all sensors (paginated, as suggested by @Ian Jacobs in the comment).
• GET /sensors/data?sensorId=1 – return data for sensor with ID = 1.
• GET /sensors/data?sensorId=1,2,3 or alternatively GET /sensors/data?sensorId=1&sensorId=2&sensorId=3 – return data for sensors with ID 1, 2, and 3.

This API is also much more flexible/extensible. You can define more filters, like time range, etc. One might imagine the following request:

GET /sensors/data?sensorId=1,2&from=2022年05月01日&to=2022年05月13日

• JoshG: Thanks! But if a user sends a GET to /sensors/<sensor_ids> they currently receive information about that sensor or collection of sensors (i.e., metadata). For example, the type of sensor, what it measures, where it's located, when it was installed, etc. And a GET to /sensors/<sensor_ids>/data gives the data recorded by that sensor. I'm not sure how the former case would work under the scheme you proposed.
• JoshG: But we do have filters set up on the Data resource. So similar to your example, passing parameters in the query string is possible. Currently this is just start and end dates but could be expanded upon.
• Archie: What stops you from having /sensors?sensorId=1 for metadata, then? :) You can also extend this filtering by e.g. sensor name, measurement, etc.
• JoshG: True, that's a good point. I like the idea. Thanks so much for the suggestion!

Answer 2

Since all is not a resource, you shouldn't use it in a resource URL but data, however, is so /sensors/data is the more correct option.

Answer 3

There is no need to insert a unnecessary /all in the route. Keep it simple and short. GET /sensors/data is absolutely fine. /sensors/all/data could also cause trouble if all is a valid id.