Feedback on API Design
Hi Bose Team,
as I'm implementing your SoundTouch API as Java Library I wanted to give some Feedback on the SoundTouch API from a Devs perspective
If you do List, design them in the same way in echt usecase. Currently different concepts -- even within one endpoint Eg
- "Info" has a list of NetworkInfo Elements which is not indicated as a list at all
- "Sources" has list of SourceItems; (One Though: A list of Sources should contain sources, right?)
- "Info" has list of Components, which holds Component Elements; "Errors" hold multiple Error Elements and Presets has Preset Elements.
Boolean Valus are sometimes prefixed with "is" and sometimes they are not, eg:
- "Sources": isLocal="true" multiroomallowed="true"
- "NowPLaying" isFavoite="true" rateEnabled="false"
It would be nice to have some parameters in the APIs eg
- "Sources": eg: give me the AUX or the SPOTIFIY source only, by passing a GET parameter.
- "Info": What is Component?, What is the 'margeUrl' for? Have some more obvious Naming would be great.
- "Key": The Response is quite unspecific. That does it mean? Did it work? (at least add the Button I pressed; eg: if I do async Implementations)
- "Volume: The Volume Endpoint allows me to check for "Mute"; but setting requires the "Key" Endpoint.
- "Key/Preset": The response does not have the deviceID Attribute (but the errorResponse has it);
Conistency in Case
- Some Elements are 'CamelCase' some are 'pascalCase' some are all lowercase. (updatedOn on "Presets")
- "NowPLaying": ContentItem starts with a capital 'C'
- "Volume": actualvolume/targetvolume are all lowercase (as well as other attributes)