Forum Discussion

stokestack's avatar
stokestack
Occasional Contributor
4 years ago

If you're controlling a device, is it best to provide an endpoint for every setting?

Hi all. Just looking for "best practice" advice here. Let's say you're creating an API to control a network-connected device, for example a camera. You might design a "camera" object schema that looks like this:

Camera
    shutterSpeed
    availableShutterSpeeds
    FStop
    availableFStops
    focusDistance
    focusDistanceMin
    focusDistanceMax
 
Let's say you have an endpoint devices/camera, and a GET on it returns the above structure. What's the best practice for letting the API user set the F-stop, then? An endpoint of devices/camera/fstop to which they can PUT a value? And do they use query parameters, or a payload in the body?
 
If you allowed a PUT of an entire camera structure, the user might attempt to set read-only values (like the list of available F-stops) along with settable values; then you'd have to convey this complicated condition in the response.
 
I'm planning to return the above camera structure, along with a set of links that allows access to every modifiable setting. So the above structure plus
 
devices/camera/shutterSpeed
devices/camera/FStop
devices/camera/focusDistance
 
Is that reasonable, or is there some more-elegant way?
No RepliesBe the first to reply