[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!"



Stuart McLean   

EXPECTINGTOFLY PLUGINS :
    
- *BBC Sounds* : 
  https://github.com/expectingtofly/LMS_BBC_Sounds_Plugin 
- *Virgin Radio (UK)* : 
  https://github.com/expectingtofly/LMS_Virgin_Radio_Plugin 
- *Times Radio* : 
  https://github.com/expectingtofly/LMS_TIMES_RADIO_PLUGIN 
- *Global Player (UK)* : 
  https://github.com/expectingtofly/LMS_GlobalPlayer_Plugin 
  
For BBC Sounds help see the 'BBC Sounds Wiki'
(https://github.com/expectingtofly/LMS_BBC_Sounds_Plugin/wiki).
------------------------------------------------------------------------
expectingtofly's Profile: http://forums.slimdevices.com/member.php?userid=63263
View this thread: http://forums.slimdevices.com/showthread.php?t=115143