[mythtv] Services API for ChannelServices / Channel

[Roger Siddons]

On Mon, 2 Dec 2019 16:19:15 -0600
David Engel <david at istwok.net> wrote:

> I know I'm late to this discussion.  My last week has been hectic.
> 
Not as late as me.

> I know the API layer allows for version numbers for each entry point.
> Does anyone know if it also does for the abstract types too (i.e
> VideoSource, Channel, etc.)?  IMHO, for each entry point, we should
> strive to support at least two versions -- the one for the current,
> MythTV release and the one for the previous, MythTV release.
> 
> Does anyone know if (and how) the API layer allows for multiple
> versions of the same entry points to be supported simultaneously?
> I've not seen how to do it.  If we don't have that capability, I
> suggest we brute force it by appending the MythTV, major, version
> number to anything that changes.  For example, with the recent
> buquet_id and region_id changes, any types and methods that were
> changed would use a new, "31" suffix.
> 

Adding version numbers is a bad idea - we don't want to convert the 
services back into a re-implementation of MythProtocol.

A backend only implements a single version (the latest) of an
entry-point, i.e mythbackend.30 implements v1.6 of the Channel
entry-point whilst mythbackend.31 will, seemingly, implement v1.7.

All endpoints of the service should be backwardly-compatible, but that's
easier than you think.

The pertinent point is that MythProtocol is designed for binary data -
it is impossible to decode anything without the encoding version/schema.
Whereas REST services work with structured data (JSON/XML/HTTP)
- extract whatever you know about and safely ignore the rest.

Therefore the version number actually specifies the minimum set of data
present; extra (unintelligible) data from later versions is ignored. For
backend endpoints that will manifest as receiving extra, unknown http
args. For clients, some parts of the JSON result won't be parsed.

Thus the golden rule of services: Removing (or renaming) existing
parameters/fields will break backward-compatibility
(a major version change). But adding new ones is fine.

Note I'm not entirely clear where bouquet fits in - I'm assuming its a
new channel property.

So, add bouquet_id etc. to ChannelInfo(?) & bump
the minor version. Follow Paul's example:
https://github.com/MythTV/mythtv/commit/63a5a20ec2b1ce908f99ffcc55eb65adfae575f2

There are functional considerations, which translates as: Don't assume
the client is speaking the same version. Usually that means new
parameters should be optional with sensible defaults, and retain old
behaviour.

The backend advertises its service version
({backend_ip}/Channel/version). But an endpoint can't know what version
the client is using (multiple clients may use different versions).
Therefore it's up to the client to negotiate/downgrade to the backend
version, or suffer the consequences.

Suppose I have 2 backends & 2 clients: 
- be6 (running myth.30, providing Channel service 1.6) 
- be7 (running myth.31, providing Channel service 1.7)
- client6 (using Channel service 1.6)
- client7 (using Channel service 1.7)

Hopefully client6/be6 & client7/be7 work as expected!

With client6/be7, the client will be ignorant of any bouquet_id the
backend emits and so will never return it as an HTTP arg. Is the request
now invalid ? But it works ok with be6! So a backend endpoint should
fallback to old (be6) behaviour if bouquet_id isn't supplied.

With client7/be6, the backend will be ignorant of any bouquet_id the
client specifies, so may deduce its own. That might surprise the client,
but it shouldn't be so ignorant as to use version 1.7 parameters with
a 1.6 service.

> What is this m_parsedParms?  I seem to have missed it.  Is it
> something that states which paramerters are provided in an API
> invocation?
> 
Yes. It arose from a thread on the developers list 05/Mar/17, "Add
method to update the metadata for a video  using the ServicesAPI"
http://lists.mythtv.org/mailman/private/mythtv-developers/2017-March/005721.html