Feedback on API Design

Feedback on API Design

geri-mgeri-m Posts: 9Member

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.
  • Design

    • "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)

Cheers, geri-m

Comments

  • edited 09/17/2018 - 08:52
    Zach@Bose[email protected] Posts: 157Admin

    Hi geri-m,

    Thank you so much for taking the time to write up all of this feedback. As we mentioned in a recent blog post, from a development standpoint, our team is focused on the upcoming Smart Home API going forward. As a result, we may not make many of these changes on the SoundTouch API, but we absolutely will be considering this feedback as we design of the Smart Home API.

    That said, we are absolutely committed to continued support of the SoundTouch API as it exists today (as it will still serve millions of devices for the foreseeable future), and that includes evolving our documentation, so we will be working on incorporating improvements into the SoundTouch API based feedback you've given here and in other threads.

    Thanks again for your work on this Java library, and the time you are putting in to give us this feedback - it is invaluable to us.

    -Zach

  • geri-mgeri-m Posts: 9Member

    Zach,

    thanks for the reply. Jop, I read about the new API and it makes sense to force on the new stuff. If at some point in time there is something you can share front up, feel free to let me know. (drop me an email, if u like) Happy to give Feedback.

    Bwt: are there Bose Dev Events in Germany? (or is there some representative around here in German for Bose Dev Relations?)

    Cheers, Gerald

Sign In or Register to comment.