[mythtv] API interfacing

Philip Brady phil.brady at hotmail.co.uk
Thu Dec 10 13:11:42 UTC 2015


I've just started lurking in this forum but I have some observations about the new API interface and the way it's going.   These are the result of writing a channel editor (now in beta) and of trying to update the documentation.

I must say at the outset that the API interface is an exciting development and will when it stabilises will be a real trigger for new contributors and a set of useful utilities.  I'm also aware that it's still work in progress so any remarks are not meant to be critical.

This post though is an attempt to highlight some of the frustrations and problems of the API interface from the point of view of an application developer.

Firstly, a bit of history.  Those wanting to interrogate or change the database had a number of options:
1.  SQL.  A bit dangerous except in expert hands.

2.  The old 'protocol' stack.  Problems with version control and insistence on key checking meant that application development could only lag MythTV development.  What you write today will need to be validated and changed with the next release.

3.  Perl bindings.  I suspect that this uses a combination of the above.  If I had been able to find documentation it may well have sparked my imagination - as it is there are few applications.

4.  Python bindings.   I do not speak Python but it appears to be documented and has a number of published applications using it.  What is the long term future for those applications?  Are the bindings and the underlying code going to be maintained well into the future so these useful utilities still work or is it possible to create a 'shim' piece of code to take binding calls and turn them into API calls?

Turning to the APIs - again I'll stress that I find they offer an exciting future but there are a number of obstacles which budding software authors need to overcome.  Apart from understanding the real user requirements of your application, the problems of making it universal and international the author then needs:
 
a)  documentation  and
b)  future-proofing.

a)  Taking the documentation first:  there are a number of sources of documentation.  

- The wiki is a useful start but it is incomplete.

- The wsdl interface describes your particular setup (eg 0.27) but does not say what is coming down the line with 0.28.  I've scanned these and extracted useful info and created the 0.27 and 0.28 parameter pages in the wiki.  (Thanks to Bill for supplying the 0.28 data to me!) but that will need doing for 0.29 and later releases as early in development as feasible.

- Your own host will provide information for GET operations.

- You could delve down into the code - but if we have to go that far then we have failed.

Short of the code delving, there is still a big hole in the documentation:  which parameters are mandatory and what are their defaults if not?  That information is not available.  There is also the question of what the calls do and what the parameters mean.  Some will argue that if you cannot work it out then you should not delve, but some subtleties do need explanation (eg StartTS or StartTime, IconURL or Icon).
  

b) Future proofing

We must recognise that the API interface will change.  Acknowledging that, how can we write code defensively so that the changes made by developers do not impact us and that our code written and tested with 0.27 will still work with 0.37?  Can we code around the likely changes and make sensible and correct choices, or can we at least crash if the unexpected occurs rather than trampling over the database of a trusting end user?

What are the sort of hazards I hit?  What did I learn which prompted me to write the module in the Perl API examples wiki (even though it does not help those who for good reason prefer Python or any other language).

1.  A bug really - GetRecordedList  startindex=0 and startindex=1 give the same result.  If you grab data in chunks you will get a duplicate.  Defence:  grab everything in one go (to hell with memory usage) OR look for and ignore the duplicate.

2.  GetChannelInfoList  - new parameters were introduced in 0.28.  Unfortunately, the defaults did not match 0.27 behaviour so data was missing when tried with 0.28.  Fortunately though, 0.27 quietly ignores the new parameters so they can be included if authors are aware of it.  The lesson is that authors need warning, they also need to ensure that their application crashes if the data is missing.
It was that incident which led me to writing the 0.27 parameters and 0.28 parameters lists in the wiki.

3. Mismatched parameter names.  I think that the intention is that for example to hide a channel you would 'GetChannelInfo', change the single parameter (Visible), then write back with a post 'UpdateDBChannel'.  Sounds simple.

Sadly, many of the names do not match.  Visible or visible?  ChannelID or ChannelId?  ChanNum or ChannelNumber?  Unless action is taken the database will (or may) be trampled on.  We suspect that these will be ironed out in favour of consistency but how do we code our way round that?
My defence is to read the wsdl data, decide the parameters needed, 'fuzzy match' those considered safe (lower case match, Channel for Chan etc) and crash if I cannot match.  That did not work too well with 0.28 when I first had an example of the changed the format of the wsdl and it returned no parameters but fortunately other checks prevented continuing and corrupting the database and the code is now fixed.

That still leaves IconURL in the get (not in the post) and Icon in the update (but not returned by the get).  Still not sure what that is about but I'm reliably informed that I can default the Icon parameter.  Bug or feature?

4.  Get or Post?  Quite rightly, calls which change the database shoud be posts and where that's wrong it needs changing.  Again, we need to be able to decide which it is and get or post appropriately.

5.  Change of name of call.  If I wish to delete a recording in 0.27 I need to use RemoveRecoded.  In later versions I'd need to use DeleteRecorded.  So, I now need to consult the wsdl at run time to see which I need to use.  Was that change really necessary?  


So, what is my message to developers?

1. In my first job there was a notice on every wall:   The job's not done until the paperwork is finished (with a rather rude sketch)!   Documentation please!!  And please use Mythtv release numbers rather than API versions if there are changes (eg in RemoveRecorded).  Some of us can chip in and paste in mundane stuff (like examples of 'get' calls) but not on meanings of parameters and whether they default.

2.  we really need stability of those calls already coded.

3.  If you do introduce consistency into parameter names (I see you have changed 'visible' in 0.28) then please preserve the names in GetSomethings at the expense of those in the Posts.  The latter are easier to accommodate and may well be accommodated by the fuzzy matching.

4.  Could the wsdl be expanded to say which parameters are mandatory? (and can I have an early example please?).

I think a really useful call would be 'AddRecording'.  The code for supplying the information could be a real challenge but it could allow re-introduction of 'lost' database records or even migration of recordings from other systems. 

"Just because I'm paranoid it doesn't mean that the API interface isn't still out to get me!"

Phil






 		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mythtv.org/pipermail/mythtv-dev/attachments/20151210/0f22f09d/attachment.html>


More information about the mythtv-dev mailing list