Home of the Squeezebox™ & Transporter® network music players.
Page 1 of 3 123 LastLast
Results 1 to 10 of 25
  1. #1
    Senior Member
    Join Date
    Aug 2014
    Location
    UK
    Posts
    559

    [In Development] RESTful API for LMS

    A couple of weeks ago I wanted to do a small integration project with LMS and had a look at the CLI. Although it is obviously excellent with deep integration into LMS and a big part of its success, it is not really designed for a casual integration.
    It appears to be tightly coupled to how LMS works internally, and it doesn't really use industry standards which makes for a steep learning curve for anyone who comes to it afresh or casually for a small integration. It also appears to me to be quite stateful (from what I looked at)

    I think there is room for LMS to have a RESTful API in addition to the CLI/JSONRPC, REST API's have a lot going for them :

    • They can be specified using openAPI (swagger) standards, which means they usually have good documentation (they can be self documenting).
    • They use an industry standard approach, with a structure that can be logical and therefore approachable for anyone who wants to integrate.
    • Client stubs can be automatically generated for most languages making it easy for a developer to get started with an integration.
    • The interface specification can be independently versioned, giving an integrator confidence that their code won't break with newer LMS versions. Also breaking changes can be introduced as a new version without fear of breaking clients.


    So, I've decided build a REST API for LMS! It is very early days and it is going to take me a while to plod through it (although anyone is welcome to join in) It seems like a fun project with a chance for me to get to know more about the inner workings of LMS.

    Here's where I have got to so far in these early stages :

    Specification
    I'm specifying the api as an openAPI (swagger) yaml document. This means that it is viewable using the Swagger API tools.
    I've included that in the git hub project, so the API in its current specification state is viewable here : https://expectingtofly.github.io/LMS_REST_API_Plugin

    As you can see, it is taking shape, but nowhere near finished. The /players/ route is the most complete. I've put put the basic routes in place, in particular I need to put some thought into the /Library and /Browser routes. I plan to fill in the return specifications as I build each operation, so the return specs are particularly sparse.

    Implementation
    I've started implementing the REST API as a plugin to get the routing in place and the basic pattern. You can see my progress on github here : https://github.com/expectingtofly/LMS_REST_API_Plugin

    It is functional, this is what I have done so far :

    - I've put in place a routing rules engine (Router::Simple), which is nice and light with few dependencies, which is perfect for our uses, where we already have the LMS web framework.
    - I've built the routing matching pattern and specified a few of the routing rules to get started (A routing rule returns a controller and an action).
    - I've written the controler/action mappings to the operations.
    - I've written two controllers (Players.pm and Player.pm) to put in place the pattern.

    I've written 4 routes/operations to illustrate how the it all fits together:
    Code:
    GET  /restapi/Players                      Gets a list of players
    GET  /restapi//Players/{playerid}          Gets the details of single player
    GET  /restapi//Players/{playerid}/status   Gets the power status of a player
    POST /restapi//Players/{playerid}/status   Sets the the power status of a player
    The Goal
    I plan to plod my way through all this and see how far it can go. Obviously, there is absolutely no point in doing this if nobody is ever going to use the API. So, the ideal scenario is, it can be taken to sufficient level of quality/maturity that the plugin could be considered for inclusion in the standard LMS distribution. Time will tell if it can reach that level of maturity. Who knows, I may reach a stumbling block and find out just why nobody has ever done this before!

    I just wanted it to be known that I am working on it and anyone who likes doing this kind of thing (I maybe alone in that!) is more than welcome to join in.

    All feedback welcome, even if it is to tell me "you are wasting your time, we already have the CLI/JSON, nobody will ever use it!"

  2. #2
    Babelfish's Best Boy mherger's Avatar
    Join Date
    Apr 2005
    Location
    Switzerland
    Posts
    20,628

    [In Development] RESTful API for LMS

    > A couple of weeks ago I wanted to do a small integration project with
    > LMS and had a look at the CLI. Although it is obviously excellent with
    > deep integration into LMS and a big part of its success, it is not
    > really designed for a casual integration.


    What feature set would you have required? I would agree that it can
    clearly be overwhelming.

    > I think there is room for LMS to have a RESTful API in addition to the
    > CLI/JSONRPC, REST API's have a lot going for them :


    Trust me: I thought of doing this myself before! :-)

    I mostly never tried it because it was more of a nerd's urge rather than
    an actual need to do it.

    > I've started implementing the REST API as a plugin to get the routing in
    > place and the basic pattern. You can see my progress on github here :
    > -https://github.com/expectingtofly/LMS_REST_API_Plugin


    What I'd recommend is that you translate as much as possible into CLI
    commands. Eg. there's no need to re-implement the player status
    response, which certainly then would be different from what users might
    have expected or see in different applications. Better use the built-in
    "status" query to make sure you get the same raw data, then transform
    this into whatever you think should be the response.

    And instead of restapi I'd probably just use the api path. It's not
    taken yet, is it?...

    > I plan to plod my way through all this and see how far it can go.
    > Obviously, there is absolutely no point in doing this if nobody is ever
    > going to use the API.


    You picked a great starting point IMHO. I could imagine quite a few use
    cases to have easy access the player status. Maybe have some playback
    control.

    Would I would put rather far down the list is full data browsing. This
    is so complicated with the various browse modes, all vs. primary artists
    only, compilations etc. it might be hard to make this return the
    expected results without adding support for the same set of query
    parameters.

    > All feedback welcome, even if it is to tell me "you are wasting your
    > time, we already have the CLI/JSON, nobody will ever use it!"


    It'll certainly take more time than you'd think - in particular once
    people start using it :-). I'm probably not a prime candidate, but I
    certainly hope to find some time to play with this. I love well
    structured REST APIs!

  3. #3
    Senior Member philchillbill's Avatar
    Join Date
    Jan 2019
    Location
    The Netherlands
    Posts
    855
    I've been using jsonrpc.js for years so maybe I'm just very used to it by now. I remember when I started out that I thought it was such a pity that POST had to be used with it, meaning that a browser couldn't be deployed with parameter strings to interact Ś I had to use POSTman or curl.

    I'd say of you want to do a RESTful API, make it all GET-based so that everything can be done from a browser. That way, you're not just recreating a RESTful way of doing what can already be done, but you're opening a new usability angle to boot.

  4. #4
    Senior Member
    Join Date
    Aug 2014
    Location
    UK
    Posts
    559
    Quote Originally Posted by philchillbill View Post
    I'd say of you want to do a RESTful API, make it all GET-based so that everything can be done from a browser. That way, you're not just recreating a RESTful way of doing what can already be done, but you're opening a new usability angle to boot.
    Much of the point of REST apis is that it uses the HTTP verbs to indicate what you want to do to the resource indicated in the path, so it will be using GET, POST, PUT, DELETE etc.
    Last edited by expectingtofly; 2021-09-15 at 05:32.

  5. #5
    Babelfish's Best Boy mherger's Avatar
    Join Date
    Apr 2005
    Location
    Switzerland
    Posts
    20,628

    [In Development] RESTful API for LMS

    > I'd say of you want to do a RESTful API, make it all GET-based so that

    That's not the idea of REST... using the "correct" methods is an
    important part of it.

    > everything can be done from a browser. That way, you're not just
    > recreating a RESTful way of doing what can already be done, but you're
    > opening a new usability angle to boot.


    Such APIs would hardly ever be used on their own, but most likely in a
    script. Yes, for the developer it's super easy to be able to use a
    browser to test. But a developer should be familiar with the tools you
    mentioned anyway.

  6. #6
    Senior Member
    Join Date
    Aug 2014
    Location
    UK
    Posts
    559
    Quote Originally Posted by mherger View Post

    What feature set would you have required? I would agree that it can
    clearly be overwhelming.
    Yes, it wasn't so much that I couldn't use the CLI, it was that I didn't want it to be the focus of my effort. It was more that it was that that triggered the thought that there was a need.

    Quote Originally Posted by mherger View Post
    Trust me: I thought of doing this myself before! :-)

    I mostly never tried it because it was more of a nerd's urge rather than
    an actual need to do it.
    There is always that risk :-), but I'm enjoying it so far so I'll carry on with the urge :-)

    Quote Originally Posted by mherger View Post
    What I'd recommend is that you translate as much as possible into CLI
    commands. Eg. there's no need to re-implement the player status
    response, which certainly then would be different from what users might
    have expected or see in different applications. Better use the built-in
    "status" query to make sure you get the same raw data, then transform
    this into whatever you think should be the response.
    Sure, I'll try and keep it simple. I did briefly look at the statusquery, but I was concerned that it looked specifically engineered to support tightly coupled user interfaces, and I didn't want to fall into a trap of exposing the same out of a REST API. I'll look again.

    Quote Originally Posted by mherger View Post
    And instead of restapi I'd probably just use the api path. It's not
    taken yet, is it?...
    good point, I'll change it.

    Quote Originally Posted by mherger View Post
    Would I would put rather far down the list is full data browsing. This
    is so complicated with the various browse modes, all vs. primary artists
    only, compilations etc. it might be hard to make this return the
    expected results without adding support for the same set of query
    parameters.
    Yes, good point, I've tried to put that to the back of my mind for the moment so I could get started :-)

  7. #7
    Senior Member philchillbill's Avatar
    Join Date
    Jan 2019
    Location
    The Netherlands
    Posts
    855
    Quote Originally Posted by expectingtofly;
    Much of the point of REST apis is that it uses the HTTP verbs to indicate what you want to do to the resource indicated in the path, so it will be using GET, POST, PUT, DELETE etc.
    Oh sure I know but I was just thinking that bending the rules to make a more user-friendly tool might be preferable above sticking religiously to the definition of REST. As an example. Domoticz uses GET for everything in its API and it's really useful to be able to bookmark long URL-strings to do stuff.

  8. #8
    Senior Member
    Join Date
    Aug 2014
    Location
    UK
    Posts
    559
    Quote Originally Posted by philchillbill View Post
    Oh sure I know but I was just thinking that bending the rules to make a more user-friendly tool might be preferable above sticking religiously to the definition of REST. As an example. Domoticz uses GET for everything in its API and it's really useful to be able to bookmark long URL-strings to do stuff.
    No, really, its essential. Its not a question of bending the rules. It needs to use the correct HTTP verb for the operation that you want on the resource, otherwise it just doesn't work.

  9. #9
    Senior Member philchillbill's Avatar
    Join Date
    Jan 2019
    Location
    The Netherlands
    Posts
    855
    Quote Originally Posted by expectingtofly;
    No, really, its essential. Its not a question of bending the rules. It needs to use the correct HTTP verb for the operation that you want on the resource, otherwise it just doesn't work.
    It's your party, but

    Code:
    GET  /restapi//Players/{playerid}/status   Gets the power status of a player
    POST /restapi//Players/{playerid}/status   Sets the the power status of a player
    can be just as easily done as

    Code:
    GET  /restapi//Players/{playerid}/status       Gets the power status of a player
    GET /restapi//Players/{playerid}/status=on  Powers on a player
    GET /restapi//Players/{playerid}/status=off  Powers off a player
    That's what the Domoticz guys did. I know, I know, it's not RESTful, but it's certainly useful and even noobs get it.

  10. #10
    Senior Member
    Join Date
    Aug 2014
    Location
    UK
    Posts
    559
    Quote Originally Posted by philchillbill View Post
    That's what the Domoticz guys did
    Bizarre.

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •