Difference between revisions of "Services API"
(An extremely basic start. I'll do more later.)
Revision as of 01:31, 2 October 2011
What is the Services API
The Services API is a new set of APIs (Application Programming Interfaces) taking the place of MythXML in MythTV versions .25 and later. It is an extremely featureful set of interfaces designed to allow one to configure MythTV, access MythTV content, control your DVR, use MythTV as a service in your own applications, and otherwise make MythTV accessible to any and everyone.
The Services API uses regular HTTP POST and GET commands, and can return both JSON and XML output by setting the HTTP accepts header appropriately.
The Services API is organized into services, which are logical groupings of APIs by their function and purpose. The individual methods contained in each service are documented on the service's wiki page.
Accessing an API is as simple as connecting to the backend's web server port (the default is 6544) at the service name's subdirectory, followed by the method and its arguments in standard HTTP format. For example, one of the simplest APIs is the SendMessage API, which is a part of the Myth service. The SendMessage API takes three arguments, but only one is necessary, the Message which is the message text to be broadcast to running frontends (by default, to all of them). So, we would construct our API command this way:
This particular API has a boolean return value-- a true or false XML or JSON result that tells the application that the message was sent, or failed for some reason. A result for the above command would be:
If you mistype a parameter, the backend's web server may throw an error. If we mistype "SendMessage" as "SendMassage", the backend throws:
Because this is not a valid API. Individual APIs may also do their own sanity checking regarding required parameters, acceptable values, and other basic requirements.
How to use the APIs
While it is possible to call most if not all of the APIs from a browser, the true power of the system is exposed when they are used programmatically. You might choose to wrap the API library in a C, Java, Cocoa, or other wrapper so that all of this functionality can be used from a program of your own. You might choose to write an alternative frontend (that won't break every time the protocol or database schema changes), a web interface, or your own setup application!