[mythtv] Services API for ChannelServices / Video Source

[David Engel]

On Fri, Nov 01, 2019 at 08:54:18AM +0000, Stuart Morgan wrote:
> On Friday, 1 November 2019 07:12:07 GMT Gary Buhrmaster wrote:
> > On Thu, Oct 31, 2019 at 9:43 PM Klaas de Waal <klaas.de.waal at gmail.com> 
> wrote:
> > > I have committed support for the bouquet ID and the region ID in the
> > > services API  but not yet tested anything.
> > 
> > I would hope the documentation will be updated.
> > 
> > And changes to the Services API brings up the
> > regular repeated issue of versioning of the services
> > API invokations when new required fields are added
> > in order to support backwards compatibility for existing
> > users of the API.  if the project wants to use the model
> > of the API is not stable (and get over it), then versioning
> > does not matter, but that also means the Services API
> > should not be used outside of project provided scripts
> > because they will break whenever in various ways.
> 
> The services API was intended to retain backwards compatibility at all times, 
> although in the early days some breaking changes were necessary to bring the 
> API endpoints into line with each other. It has repeatedly been stated that 
> the Services API is the true public interface to the system and that third 
> party software using the internal protocol should switch to it for this very 
> reason.
> 
> As such changes which break compatibility would require a new endpoint to be 
> created. Usually this is avoidable, especially when we're just talking about 
> new parameters being added, since these can be made optional with sane default 
> values.
> 
> A proper versioning system, where the client specifies the version they 
> understand and requests are handled accordingly would be good to have.

I am nearly, totally unfamiliar with the inner workings of the
services code or I would have tried fixing some of the issues.  I see
things we need to be able to handle multiple versions of endpoints and
advertise which ones we support.

Unless someone knows how to do that, perhaps we could get by using an
ugly, brute force technique of including a version indication in the
endpoint name itself.  For exaplle, when the UpdateWidget endpoint
needs an incompatible change, add a new UpdateWidget2 endpoint and
change the old, AddWidget endpoint to either do the right thing of
fail gracefully.

Also, another failing of the current API is the inability to pass an
"unspecified" indication to the endpoint.  In some cases, it's
possible to use an empty string or numeric 0 but that doesn't work
everywhere where such values are valid.  It might be nice if the API
layer could pass something like QVariants which could be tested to see
if they are of the expected type or are "NULL".

David
-- 
David Engel
david at istwok.net