stokestack
4 years agoOccasional Contributor
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?