Difference between revisions of "Services API"

From MythTV Official Wiki
Jump to: navigation, search
(Added v30 and v31)
(Add "Authentication and Authorization" documentation)
 
(5 intermediate revisions by 3 users not shown)
Line 72: Line 72:
  
 
:* [[Microsoft.Net / WCF]]
 
:* [[Microsoft.Net / WCF]]
 +
 +
=Scripting and testing=
 +
 +
The methods from  the wsdl that list GET can be run from a browser and will return xml results. If the xml is huge, for example guide data, the browser can hang for a long time.
 +
 +
Here are some examples of how the API can be run from a command line or script.
 +
 +
The GET and POST methods can be run from curl:
 +
curl "http://localhost:6544/Myth/GetTimeZone"
 +
 +
Get json results from curl
 +
curl -H "Accept: application/json" "http://localhost:6544/Myth/GetTimeZone"
 +
 +
Get json results formatted nicely from curl
 +
curl -s -S -H "Accept: application/json" "http://localhost:6544/Myth/GetTimeZone" | jq
 +
 +
Extract a field from the results
 +
curl -s -S -H "Accept: application/json" "http://localhost:6544/Myth/GetTimeZone" | \
 +
jq -r '.TimeZoneInfo.TimeZoneID'
 +
 +
Extract a list of video Filenames and watched indicators
 +
curl  -s -S -H "Accept: application/json" \
 +
    "http://localhost:6544/Video/GetVideoList" \
 +
    | jq -r '.VideoMetadataInfoList.VideoMetadataInfos[] | {FileName,Watched} | join("\t")' \
 +
    > $DATADIR/videos.txt
 +
 +
methods that require POST can be run with curl by specifying the option -X POST.
 +
 +
=Authentication and Authorization=
 +
 +
{{VersionNote|36|Authentication and Authorization is added in V36}}
 +
 +
For people who wish to expose the API and the Web App to the internet, there is now optional login/password protection.
 +
 +
The API methods are protected by an access token, which is provided by a Login call. Maintenance of user ids and passwords is through the API or the web app. See the web app documentation for more information. Authentication is by default not required. It can be enabled for all IP addresses or remote IP addresses.
 +
 +
The calls and parameters described here are only needed if you enable authentication for all IP addresses or if you enable it for remote IP addresses and then intend accessing it remotely.
 +
 +
wsdl is not protected, does not require a login. Myth/LoginUser and Myth/GetConnectionInfo are not protected. All other methods are protected. The settings that enable or disable required authentication are further protected by requiring admin login. The Myth/ManageDigestUser, which updates and deletes users, restricts operations to the admin user, except those that update your own user id. If "authentication required" is disabled, Myth/ManageDigestUser allows all operations with no user login, but still restricts them when a user id logged in..
 +
 +
When using the Service API with authentication required, you need to first login:
 +
 +
curl -i -X POST "http://localhost:6544/Myth/LoginUser?UserName=peter&Password=peter"
 +
 +
You receive a response in xml format (or json if requested), with the authorization token:
 +
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<String xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" serializerVersion="1.1">
 +
6afb519ff9eeccf6d6643b012391c511a13640c2
 +
</String>
 +
 +
If the login is invalid an empty string is returned:
 +
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<String xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" serializerVersion="1.1"></String>
 +
 +
Then, when calling other methods include the authorization token as a header field, for example:
 +
 +
curl -H "Authorization: 6afb519ff9eeccf6d6643b012391c511a13640c2" "http://localhost:6544/Myth/GetTimeZone"
 +
 +
Also supported is adding it as a parameter
 +
"http://localhost:6544/Myth/GetTimeZone?authorization=6afb519ff9eeccf6d6643b012391c511a13640c2"
 +
 +
Scripting example:
 +
 +
auth=$(curl -s -S -X POST -H "Accept: application/json" \
 +
    "http://localhost:6544/Myth/LoginUser?UserName=$API_USER&Password=$API_PASSWD" \
 +
    | jq -r '.String')
 +
# List of video Filenames and watched indicators
 +
curl  -s -S -H "Accept: application/json" \
 +
    -H "Authorization: $auth" \
 +
    "http://localhost:6544/Video/GetVideoList" \
 +
    | jq -r '.VideoMetadataInfoList.VideoMetadataInfos[] | {FileName,Watched} | join("\t")' \
 +
    > $DATADIR/videos.txt
  
 
=Current Services=
 
=Current Services=
  
−
'''You can click the title of any service to see documentation on the individual APIs.'''
+
'''You can click the title of any service to see documentation on the individual APIs.''' The services offered are added to frequently, so it is best to start up mythbackend and run the wsdl ujrl aas described above, to get a comprehensive list of input parameters and result fields.
  
 
==[[Capture Service]]==
 
==[[Capture Service]]==
Line 84: Line 158:
  
 
The '''Channel''' service is a collection of methods for editing channels, adding channels, deleting channels, and modifying lineups and XMLTV services.
 
The '''Channel''' service is a collection of methods for editing channels, adding channels, deleting channels, and modifying lineups and XMLTV services.
 +
 +
==Config Service==
 +
 +
The '''Config''' service provides methods for system configuration.
  
 
==[[Content Service]]==
 
==[[Content Service]]==
Line 100: Line 178:
  
 
The '''Guide''' service is a group of methods for accessing the program guide information for use in scheduling, and guide grid applications.
 
The '''Guide''' service is a group of methods for accessing the program guide information for use in scheduling, and guide grid applications.
 +
 +
==Music Service==
 +
 +
The '''Music''' service provides access to metadata for items stored in the Music plugin.
  
 
==[[Myth Service]]==
 
==[[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.
 
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.
 +
 +
==Status Service==
 +
 +
The '''Status''' service provides a method for the backend system status page, plus legacy html and xml versions of that, for compatibility with older systems.
  
 
==[[Video Service]]==
 
==[[Video Service]]==
Line 124: Line 210:
 
===[[API parameters 31]]===
 
===[[API parameters 31]]===
 
A list of parameters extracted from v31 wsdl pages, highlighting changes from v30.  
 
A list of parameters extracted from v31 wsdl pages, highlighting changes from v30.  
 +
<br />
 +
===[[API parameters 32]]===
 +
A list of parameters extracted from v32 wsdl pages, highlighting changes from v31.
 +
<br />
 +
===[[API parameters v32 new interface]]===
 +
A list of parameters extracted from v32 wsdl pages via the ports 6744 and 8081, highlighting changes from v32 ports 6544 and 6547.
 
<br />
 
<br />
  

Latest revision as of 19:33, 20 May 2025

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

Scripting and testing

The methods from the wsdl that list GET can be run from a browser and will return xml results. If the xml is huge, for example guide data, the browser can hang for a long time.

Here are some examples of how the API can be run from a command line or script.

The GET and POST methods can be run from curl: 

curl "http://localhost:6544/Myth/GetTimeZone"

Get json results from curl 

curl -H "Accept: application/json" "http://localhost:6544/Myth/GetTimeZone"

Get json results formatted nicely from curl 

curl -s -S -H "Accept: application/json" "http://localhost:6544/Myth/GetTimeZone" | jq

Extract a field from the results 

curl -s -S -H "Accept: application/json" "http://localhost:6544/Myth/GetTimeZone" | \
jq -r '.TimeZoneInfo.TimeZoneID'

Extract a list of video Filenames and watched indicators 

curl  -s -S -H "Accept: application/json" \
    "http://localhost:6544/Video/GetVideoList" \
    | jq -r '.VideoMetadataInfoList.VideoMetadataInfos[] | {FileName,Watched} | join("\t")' \
    > $DATADIR/videos.txt

methods that require POST can be run with curl by specifying the option -X POST.

Authentication and Authorization

Version:
36
 Authentication and Authorization is added in V36

For people who wish to expose the API and the Web App to the internet, there is now optional login/password protection.

The API methods are protected by an access token, which is provided by a Login call. Maintenance of user ids and passwords is through the API or the web app. See the web app documentation for more information. Authentication is by default not required. It can be enabled for all IP addresses or remote IP addresses.

The calls and parameters described here are only needed if you enable authentication for all IP addresses or if you enable it for remote IP addresses and then intend accessing it remotely.

wsdl is not protected, does not require a login. Myth/LoginUser and Myth/GetConnectionInfo are not protected. All other methods are protected. The settings that enable or disable required authentication are further protected by requiring admin login. The Myth/ManageDigestUser, which updates and deletes users, restricts operations to the admin user, except those that update your own user id. If "authentication required" is disabled, Myth/ManageDigestUser allows all operations with no user login, but still restricts them when a user id logged in..

When using the Service API with authentication required, you need to first login: 

curl -i -X POST "http://localhost:6544/Myth/LoginUser?UserName=peter&Password=peter"

You receive a response in xml format (or json if requested), with the authorization token: 

<?xml version="1.0" encoding="UTF-8"?>
<String xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" serializerVersion="1.1">
6afb519ff9eeccf6d6643b012391c511a13640c2
</String>

If the login is invalid an empty string is returned: 

<?xml version="1.0" encoding="UTF-8"?>
<String xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" serializerVersion="1.1"></String>

Then, when calling other methods include the authorization token as a header field, for example: 

curl -H "Authorization: 6afb519ff9eeccf6d6643b012391c511a13640c2" "http://localhost:6544/Myth/GetTimeZone"

Also supported is adding it as a parameter 

"http://localhost:6544/Myth/GetTimeZone?authorization=6afb519ff9eeccf6d6643b012391c511a13640c2"

Scripting example: 

auth=$(curl -s -S -X POST -H "Accept: application/json" \
    "http://localhost:6544/Myth/LoginUser?UserName=$API_USER&Password=$API_PASSWD" \
    | jq -r '.String')
# List of video Filenames and watched indicators
curl  -s -S -H "Accept: application/json" \
    -H "Authorization: $auth" \
    "http://localhost:6544/Video/GetVideoList" \
    | jq -r '.VideoMetadataInfoList.VideoMetadataInfos[] | {FileName,Watched} | join("\t")' \
    > $DATADIR/videos.txt

Current Services

You can click the title of any service to see documentation on the individual APIs. The services offered are added to frequently, so it is best to start up mythbackend and run the wsdl ujrl aas described above, to get a comprehensive list of input parameters and result fields.

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.

Config Service

The Config service provides methods for system configuration.

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.

Music Service

The Music service provides access to metadata for items stored in the Music plugin.

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.

Status Service

The Status service provides a method for the backend system status page, plus legacy html and xml versions of that, for compatibility with older systems.

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.

Lists of API Parameters

API parameters 0.27

A list of parameters extracted from 0.27 wsdl pages.

API parameters 0.28

A list of parameters extracted from 0.28 wsdl pages, highlighting changes from 0.27.

API parameters 29

A list of parameters extracted from v29 wsdl pages, highlighting changes from 0.28.

API parameters 30

A list of parameters extracted from v30 wsdl pages, highlighting changes from v29.

API parameters 31

A list of parameters extracted from v31 wsdl pages, highlighting changes from v30.

API parameters 32

A list of parameters extracted from v32 wsdl pages, highlighting changes from v31.

API parameters v32 new interface

A list of parameters extracted from v32 wsdl pages via the ports 6744 and 8081, highlighting changes from v32 ports 6544 and 6547.

Perl API examples

Discussion of how to read data via API calls from Perl, how to sieve out the information you need, how to write back to the database and a list of some pitfalls. A perl module with routines to help with this and code examples are included.

Python API Examples

Similar to the above, but primarily a module that cares for sending/receiving API data and how to use it.

Retrieved from "http://www.mythtv.org/wiki?title=Services_API&oldid=66901"