Difference between revisions of "Services API"

From MythTV Official Wiki
Jump to: navigation, search
(An extremely basic start. I'll do more later.)
 
Line 6: Line 6:
  
 
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.
 
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'' 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:
 
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:
Line 21: Line 23:
 
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.
 
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=
+
=Proper use of 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!
 
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!

Revision as of 01:48, 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.

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 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.

Proper use of 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!

Current Services

Capture Service

Channel Service

Content Service

DVR Service

Guide Service

Myth Service

Video Service