JSON-RPC API: Difference between revisions
Jump to navigation
Jump to search
>Montellese |
>Montellese (major refactoring) |
||
| Line 1: | Line 1: | ||
JSON RPC is a HTTP- | JSON-RPC is a HTTP- and/or raw TCP socket-based interface for communicating with XBMC. It replaces the soon-to-be-depreceated HTTP API, and offers a more secure and robust mechanism in the same format. It is based upon the [http://jsonrpc.org/spec.html JSON-RPC 2.0 specification]. | ||
Each method in the interface can have different security needs which means one client may be allowed to only control playback while another can only read and manipulate the library. In version 2 (first stable) all clients are granted full authority but will later be forced to ask for privileges and the user of XBMC will have to grant said client access. The design of JSON RPC is that most methods should behave roughly the same and maintain consistency while hiding the mechanics of XBMC from the client creator. | Each method in the interface can have different security needs which means one client may be allowed to only control playback while another can only read and manipulate the library. In version 2 (first stable) and 4 all clients are granted full authority but will later be forced to ask for privileges and the user of XBMC will have to grant said client access. The design of JSON-RPC is that most methods should behave roughly the same and maintain consistency while hiding the mechanics of XBMC from the client creator. | ||
In XBMC JSON RPC can be accessed over a variety of transports and has been designed from the ground up to be flexible to allow control over new transports | In XBMC JSON-RPC can be accessed over a variety of transports and has been designed from the ground up to be flexible to allow control over new transports easily. Some of the transports have different limitations which will be enforced upon the interaction over that transport. As an example HTTP transports allow response and downloading of files while the raw TCP transport allows response and notifications (events and information XBMC sends to its clients). Depending on the client's needs it will choose one (or many) of the available transports. | ||
==Enabling JSON-RPC== | |||
== Enabling JSON RPC == | Since the interface is available on many transports enabling it depends on the transport. | ||
Since the interface is available on many transports enabling it | * Python: Always enabled | ||
* Python | * HTTP: In System/Settings/Network/Services activate ''Allow control of XBMC via HTTP'' | ||
* HTTP | * TCP: In System/Settings/Network/Services activate ''Allow programs on this system to control XBMC'' for localhost access only and ''Allow programs on other systems to control XBMC'' for access from other computers as well | ||
* TCP | |||
Note: The EventServer is a different interface for sending remote keypresses to XBMC, and must be enabled separately, some programs may use both interfaces. | Note: The EventServer is a different interface for sending remote keypresses to XBMC, and must be enabled separately, some programs may use both interfaces. | ||
== | ==Transports== | ||
===Functionalities=== | |||
TODO | |||
== | ===Comparison=== | ||
The following table shows all the available transports and what functionalities they support | |||
== | {| class="wikitable" style="margin-right:0; font-size:85%;" | ||
!style="width:15em"| | |||
!Response | |||
!Notifications | |||
!Direct file download | |||
!Redirected file download | |||
|- | |||
|[[Python Development|Python]] | |||
|{{yes}} | |||
|{{yes}} | |||
|{{no}} | |||
|{{no}} | |||
|- | |||
|[http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] | |||
|{{yes}} | |||
|{{yes}} | |||
|{{no}} | |||
|{{no}} | |||
|- | |||
|[http://en.wikipedia.org/wiki/HTTP HTTP] | |||
|{{yes}} | |||
|{{no}} | |||
|{{no}} | |||
|{{yes}} | |||
|- | |||
|} | |||
==== | ==API versions== | ||
The JSON-RPC API exposed by XBMC is constantly extended to provide better and more functionality to third party applications. For that reason XBMC provides a version information through the '''JSONRPC.Version''' method. The rule is that odd version numbers describe an API state, that is not stable and under heavy development whereas even version numbers describe a stable API. Therefore the version number can be used by third party clients to check if their application might not be fully compatible with the JSON-RPC API exposed by a users XBMC installation. | |||
''' | |||
Since the first release of the JSON-RPC API in XBMC 10.0 (Dharma) there have been the following versions of the API: | |||
* [[JSON-RPC/v2|JSON-RPC v2 (Dharma)]] | |||
* [[JSON-RPC/v3|JSON-RPC v3 (pre Eden)]] | |||
=== | ==Documentation== | ||
TODO | |||
==Debugging== | |||
===Output format=== | |||
To be able to support easier debugging of (third party) development using the JSON-RPC API, the JSON output generated by XBMC can be pretty printed by setting | |||
== Debugging == | |||
=== Output format === | |||
To be able to support easier debugging of (third party) development using the JSON RPC API, the JSON output generated by XBMC can be pretty printed by setting | |||
<source lang="xml"> | <source lang="xml"> | ||
<jsonrpc> | <jsonrpc> | ||
| Line 2,175: | Line 67: | ||
in the [[Advancedsettings.xml#.3Cjsonrpc.3E|advancedsettings.xml]]. Default JSON output will be in compact format to minimize sent data (especially useful for mobile devices). | in the [[Advancedsettings.xml#.3Cjsonrpc.3E|advancedsettings.xml]]. Default JSON output will be in compact format to minimize sent data (especially useful for mobile devices). | ||
=== Direct interaction === | ===Direct interaction=== | ||
To be able to test some methods of XBMC's JSON RPC API it can be of great help to be able to send a single hand-written JSON RPC request to XBMC to see its effect and the generated response. Depending on the transport protocol used there are different possibilities to do that: | To be able to test some methods of XBMC's JSON-RPC API it can be of great help to be able to send a single hand-written JSON-RPC request to XBMC to see its effect and the generated response. Depending on the transport protocol used there are different possibilities to do that: | ||
==== TCP ==== | ====TCP==== | ||
With a '''[http://en.wikipedia.org/wiki/Telnet telnet]''' connection (using [http://en.wikipedia.org/wiki/PuTTY PuTTY] on Windows or telnet on Linux) to port 9090 of the machine running XBMC it is possible to send and receive raw json data to/from XBMC. | With a '''[http://en.wikipedia.org/wiki/Telnet telnet]''' connection (using [http://en.wikipedia.org/wiki/PuTTY PuTTY] on Windows or telnet on Linux) to port 9090 of the machine running XBMC it is possible to send and receive raw json data to/from XBMC. | ||
==== HTTP ==== | ====HTTP==== | ||
A simple way of manually sending HTTP requests containing a JSON RPC request to XBMC is using the [http://chrome.google.com/extensions/detail/fhjcajmcbmldlhcimfajhfbgofnpcjmb Simple REST Client] extension for Google's Chrome/Chromium browser. It allows defining an URL and the HTTP request type ('''POST''' is what we need). The actual JSON RPC request can be defined in the '''Data''' field and then sent to XBMC. | A simple way of manually sending HTTP requests containing a JSON-RPC request to XBMC is using the [http://chrome.google.com/extensions/detail/fhjcajmcbmldlhcimfajhfbgofnpcjmb Simple REST Client] extension for Google's Chrome/Chromium browser. It allows defining an URL and the HTTP request type ('''POST''' is what we need). The actual JSON-RPC request can be defined in the '''Data''' field and then sent to XBMC. | ||
== | ==External links== | ||
*[http://jsonrpc.org/spec.html JSON-RPC 2.0 specification] | |||
* | *[http://tools.ietf.org/html/draft-zyp-json-schema-03 A JSON Media Type for Describing the Structure and Meaning of JSON Documents (Draft 03)] | ||
* | |||
[[Category:Inner Workings]] | [[Category:Inner Workings]] | ||
[[Category:Development]] | [[Category:Development]] | ||
Revision as of 21:08, 24 October 2011
JSON-RPC is a HTTP- and/or raw TCP socket-based interface for communicating with XBMC. It replaces the soon-to-be-depreceated HTTP API, and offers a more secure and robust mechanism in the same format. It is based upon the JSON-RPC 2.0 specification.
Each method in the interface can have different security needs which means one client may be allowed to only control playback while another can only read and manipulate the library. In version 2 (first stable) and 4 all clients are granted full authority but will later be forced to ask for privileges and the user of XBMC will have to grant said client access. The design of JSON-RPC is that most methods should behave roughly the same and maintain consistency while hiding the mechanics of XBMC from the client creator.
In XBMC JSON-RPC can be accessed over a variety of transports and has been designed from the ground up to be flexible to allow control over new transports easily. Some of the transports have different limitations which will be enforced upon the interaction over that transport. As an example HTTP transports allow response and downloading of files while the raw TCP transport allows response and notifications (events and information XBMC sends to its clients). Depending on the client's needs it will choose one (or many) of the available transports.
Enabling JSON-RPC
Since the interface is available on many transports enabling it depends on the transport.
- Python: Always enabled
- HTTP: In System/Settings/Network/Services activate Allow control of XBMC via HTTP
- TCP: In System/Settings/Network/Services activate Allow programs on this system to control XBMC for localhost access only and Allow programs on other systems to control XBMC for access from other computers as well
Note: The EventServer is a different interface for sending remote keypresses to XBMC, and must be enabled separately, some programs may use both interfaces.
Transports
Functionalities
TODO
Comparison
The following table shows all the available transports and what functionalities they support
| Response | Notifications | Direct file download | Redirected file download | |
|---|---|---|---|---|
| Python | Yes | Yes | No | No |
| TCP | Yes | Yes | No | No |
| HTTP | Yes | No | No | Yes |
API versions
The JSON-RPC API exposed by XBMC is constantly extended to provide better and more functionality to third party applications. For that reason XBMC provides a version information through the JSONRPC.Version method. The rule is that odd version numbers describe an API state, that is not stable and under heavy development whereas even version numbers describe a stable API. Therefore the version number can be used by third party clients to check if their application might not be fully compatible with the JSON-RPC API exposed by a users XBMC installation.
Since the first release of the JSON-RPC API in XBMC 10.0 (Dharma) there have been the following versions of the API:
Documentation
TODO
Debugging
Output format
To be able to support easier debugging of (third party) development using the JSON-RPC API, the JSON output generated by XBMC can be pretty printed by setting
<jsonrpc>
<compactoutput>false</compactoutput>
</jsonrpc>
in the advancedsettings.xml. Default JSON output will be in compact format to minimize sent data (especially useful for mobile devices).
Direct interaction
To be able to test some methods of XBMC's JSON-RPC API it can be of great help to be able to send a single hand-written JSON-RPC request to XBMC to see its effect and the generated response. Depending on the transport protocol used there are different possibilities to do that:
TCP
With a telnet connection (using PuTTY on Windows or telnet on Linux) to port 9090 of the machine running XBMC it is possible to send and receive raw json data to/from XBMC.
HTTP
A simple way of manually sending HTTP requests containing a JSON-RPC request to XBMC is using the Simple REST Client extension for Google's Chrome/Chromium browser. It allows defining an URL and the HTTP request type (POST is what we need). The actual JSON-RPC request can be defined in the Data field and then sent to XBMC.