Difference between revisions of "Services API"

From MythTV Official Wiki
Jump to: navigation, search
(SOAP and WSDL (Web Service Description Language))
(POST-only APIs)
Line 48: Line 48:
 
=POST-only APIs=
 
=POST-only APIs=
  
It is good practice for those APIs which change data in the database (capture card creation, settings changes, etc.) to be POST only.  If you find that an API is not working, it is likely because the MythTV developers want you to think very carefully about how you use it, and it requires you to HTTP POST the data.
+
It is good practice (per HTTP 1.1 standard) for those APIs which change data or trigger an action (capture card creation, settings changes, etc.) to be POST only.  If you find that an API is not working, it is likely because the MythTV developers want you to think very carefully about how you use it, and it requires you to HTTP POST the data.
  
 
=Proper use of APIs=
 
=Proper use of APIs=

Revision as of 21:31, 3 June 2014

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.

How to Use API Methods

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 argument, 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:

http://BackendServerIP:6544/Myth/SendMessage?Message=Hello!

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:

<bool>true</bool>

If you mistype a parameter, the backend's web server may throw an error. If we mistype "SendMessage" as "SendMassage", the backend throws:

401InvalidAction

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.

So, to summarize, an API call is made using the following format:

http://BackendServerIP: + Backend Web Server Port + / + Service Name + / + API Name + ? + Arguments separated by &

Currently, all services can be called using HTTP or SOAP. Depending on the header values passed, it will send back the response data as plain XML, JSON, or SOAP wrapped XML. The header values for each are as follows:

Header Value Response Format
SOAPACTION Soap
Accept: application/json json
Accept: text/javascript json
None of the above XML

POST-only APIs

It is good practice (per HTTP 1.1 standard) for those APIs which change data or trigger an action (capture card creation, settings changes, etc.) to be POST only. If you find that an API is not working, it is likely because the MythTV developers want you to think very carefully about how you use it, and it requires you to HTTP POST the data.

Proper use of APIs

Warning.png Warning: All DateTime formats in the services API are in UTC. Regardless of the timezone of your frontend or backend, the dates produced by the APIs will be UTC. Likewise, all inputs to the API must be in UTC.

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!

SOAP and WSDL (Web Service Description Language)

Each exposed service has the ability to describe itself using WSDL. You can access it by using the following url:

Sample WSDL Web Page
http://mythbackend:6544/<service Name>/wsdl

If you navigate to the url using a browser that supports XSLT, you will be presented with a web page showing each method and parameters.

The real power comes when you supply the url to a web service proxy tool. It will take the WSDL and generate proxy classes that allow you to call the service methods in a way that is native to the tool/language you are using.

It has been tested to work with the following tools/languages

Current Services

You can click the title of any service to see documentation on the individual APIs.

Capture Service

The Capture service is a series of APIs related to the capturing of recorded content. It includes methods of settings up capture devices, card inputs, and may also be expanded in the future to more directly control those interfaces.

Channel Service

The Channel service is a collection of methods for editing channels, adding channels, deleting channels, and modifying lineups and XMLTV services.

Content Service

The Content services provides a means of serving video, music, and image content from your MythTV system's collection. Images can be dynamically scaled and served by the backend according to your request.

DVR Service

The DVR service allows the programmer to interface with recorded metadata in a variety of ways.

Frontend Service

The Frontend service is actually run on Frontend systems (default port: 6547) and allows query of location, playback status, sending remote control messages, and sending popup messages, among other tasks.

Guide Service

The Guide service is a group of methods for accessing the program guide information for use in scheduling, and guide grid applications.

Myth Service

The Myth service is dedicated to MythTV specific settings, and is a series of utility APIs for influencing the way MythTV works on a low level including Storage Group configuration, settings modification and query, hardware profiling, and database backup and repair.

Video Service

The Video service is used to query and modify video metadata, look up metadata, add new videos to the library, and other video-library-specific functionality.