{{mininav|[[Development]]}}

{{JSON-RPC API nav}}
<br />

JSON-RPC is a HTTP- and/or raw TCP socket-based interface for communicating with XBMC. It replaces the <s>soon-to-be-depreceated</s> deprecated [[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) 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.<br />

== 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'' (see [[Webserver#Enabling the webserver|Enabling the webserver]])
* 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 ==
=== Transports ===
==== Python ====
The ''Python'' transport can only be used by XBMC addons through the '''executeJSONRPC''' method provided by the '''xbmc''' python library. As it must be available to every addon in an XBMC installation it must not be enabled or disabled by the user.

==== HTTP ====
The ''HTTP'' transport can be used by third-party applications running on the same machine as XBMC or on a different machine which can access the machine running XBMC using the [http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] protocol. Because this transport allows applications outside XBMC to control XBMC, it has to be manually enabled (see [[#Enabling JSON-RPC|Enabling JSON-RPC]]) by the user.

===== POST =====
Third-party applications can access XBMC's JSON-RPC API by sending JSON-RPC requests embedded in HTTP [http://en.wikipedia.org/wiki/POST_(HTTP) POST] requests to the following URL
<pre>http://<your-ip>:<your-port>/jsonrpc</pre>

Starting with Frodo nightly builds it is mandatory to set the HTTP header field '''Content-Type: application/json'''

===== GET =====
Third-party application can access XBMC's JSON-RPC API by sending JSON-RPC requests embedded in a HTTP GET parameter called ''request''. The JSON-RPC request must be URL encoded and sent to the following URL
<pre>http://<your-ip>:<your-port>/jsonrpc?request=<url-encoded-request></pre>

==== TCP ====
The ''TCP'' transport can be used by third-party applications running on the same machine as XBMC or on a different machine which can access the machine running XBMC using the [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] protocol. Because this transport allows applications outside XBMC to control XBMC it has to be manually enabled (see [[#Enabling JSON-RPC|Enabling JSON-RPC]]) by the user. Once enabled, third-party applications can access XBMC's JSON-RPC API by opening a TCP [http://en.wikipedia.org/wiki/Internet_socket socket] on port 9090 (this port can be configured in the [[Advancedsettings.xml#<jsonrpc>|advanced settings]] file) and sending raw JSON-RPC requests over that socket. Please note that no delimiters are provided in between notifications and/or responses. As such, your client needs to be able to deal with this, eg. by counting and matching curly braces ({}).

==== WebSocket ====
The ''WebSocket'' transport has been added since Version 5 and can be used by third-party applications running on the same machine as XBMC or on a different machine which can access the machine running XBMC using the [http://en.wikipedia.org/wiki/WebSocket Websocket] protocol. The supported versions are 8 (draft [http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10 hybi-10]) and 13 ([http://tools.ietf.org/html/rfc6455 RFC 6455]). Because this transport allows applications outside XBMC to control XBMC it has to be manually enabled (see [[#Enabling JSON-RPC|Enabling JSON-RPC]]) by the user. Once enabled, third-party applications can access XBMC's JSON-RPC API by sending a WebSocket protocol handshake to the following URI
<pre>ws://<your-ip>:<configured tcp port>/jsonrpc</pre>
It is important to send the handshake on the port of XBMC's TCP server (by default 9090, but this port can be configured in the [[Advancedsettings.xml#<jsonrpc>|advanced settings]] file). After having successfully finished the handshake third-party applications can send WebSocket protocl messages over that connection.

=== Functionalities ===
==== Response ====
The ''Response'' functionality is the only functionality that should be present in every transport available as it describes the functionality to respond to a JSON-RPC request with a valid JSON-RPC response (be it an error message or an actual response).

==== Notifications ====
The ''Notifications'' functionality includes both server-side (from the server to clients) and client-side (from clients to the server) notifications. A JSON-RPC notification is a valid JSON-RPC request with no ''id'' property. Following the JSON-RPC 2.0 specification any JSON-RPC request with no ''id'' must be considered as a notification and the receiver must not send a response upon a notification.

In the specific case of XBMC, server-side notifications are used to inform clients about certain events to relieve clients of the need to periodically poll for certain events. Furthermore there are two ways of client-side notifications. Using [[/v3#JSONRPC.NotifyAll|JSONRPC.NotifyAll]] it is possible to ask XBMC to relay the message in the JSON-RPC request to all other connected clients. The second way is to send JSON-RPC requests without an ''id'' property in case the client does not care about the response (e.g. the method [[/v3#Player.Stop|Player.Stop]] does not return any useful information to the client).

==== Direct file download ====
The ''Direct file download'' functionality is the ability to directly download files from XBMC by calling [[/v3#Files.Download|Files.Download]]. In this case the term ''direct'' means that the download happens within the JSON-RPC response of the [[/v3#Files.Download|Files.Download]] request.

==== Redirected file download ====
The ''Redirected file download'' functionality is the ability to indirectly download files from XBMC by calling [[/v3#Files.PrepareDownload|Files.PrepareDownload]] and using the data received in the response to download the file over a different protocol (like HTTP, FTP ...) or another socket. As the ''Redirected file download'' is very transport specific, it must be handled separately for every transport supporting it.

=== Comparison ===
The following table shows all the available transports and what functionalities they support
{| class="prettytable" style="margin-right: 0;"
!style="padding-left: 5px; padding-right: 10px;" colspan="2"|Transport
!style="padding-left: 10px; padding-right: 10px;"|Response
!style="padding-left: 10px; padding-right: 10px;"|Notifications
!style="padding-left: 10px; padding-right: 10px;"|Direct file<br />download
!style="padding-left: 10px; padding-right: 10px;"|Redirected file<br />download
|-
|style="padding-left: 5px;" colspan="2"|[[Python Development|Python]]
|{{yes}}
|{{no}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px;" colspan="2"|[http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP]
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px; padding-right:5px;" rowspan="2"|[http://en.wikipedia.org/wiki/HTTP HTTP]
|style="padding-left: 5px; padding-right:5px;"|POST
|{{yes}}
|{{no}}
|{{no}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right:5px;"|GET<sup>1</sup>
|{{yes}}
|{{no}}
|{{no}}
|{{yes}}
|-
|style="padding-left: 5px;" colspan="2"|[http://en.wikipedia.org/wiki/WebSocket WebSocket]<sup>1</sup>
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|}
<sup>1</sup> Added in Version 5

== 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 user's XBMC installation.

Starting with XBMC v12 (Frodo) we started using a new versioning system (<major>.<minor>.<bugfix>) for the JSON-RPC API. Frodo stable is version 6.0.0 and from now on with every bugfix the <bugfix> part of the version is increased, with every feature addition to the API, the <minor> version is increased (and the <bugfix> version reset to 0) and with every backwards incompatible change, the <major> version is increased.

{| class="prettytable" style="margin-right: 0;"
!|
!colspan="2"|XBMC Release
!colspan="6"|JSON-RPC 2.0 specification
!colspan="5"|Transports
|-
!style="padding-left: 5px; padding-right: 5px; width: 6em; text-align: left;"|API Version
!style="padding-left: 10px; padding-right: 10px; width: 5em;"|Version
!style="padding-left: 10px; padding-right: 10px; width: 4em;"|Name
!style="padding-left: 10px; padding-right: 10px;"|Method calls
!style="padding-left: 10px; padding-right: 10px;"|Notifications<br />(server-side)
!style="padding-left: 10px; padding-right: 10px;"|Notifications<br />(client-side)
!style="padding-left: 10px; padding-right: 10px;"|Parameters<br />by-name
!style="padding-left: 10px; padding-right: 10px;"|Parameters<br />by-position
!style="padding-left: 10px; padding-right: 10px;"|Batch requests

!style="padding-left: 10px; padding-right: 10px;"|Python
!style="padding-left: 10px; padding-right: 10px;"|TCP
!style="padding-left: 10px; padding-right: 10px;"|HTTP POST
!style="padding-left: 10px; padding-right: 10px;"|HTTP GET
!style="padding-left: 10px; padding-right: 10px;"|WebSocket
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v2|Version 2]]
|style="padding-left: 5px; padding-right: 5px;"|10.0
|style="padding-left: 5px; padding-right: 5px;"|Dharma
|{{yes}}
|{{yes}}
|{{no}}
|{{yes}}
|{{no}}
|{{no}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v3|Version 3]] / [[/v4|4]]
|style="padding-left: 5px; padding-right: 5px;"|pre-11 / 11.0
|style="padding-left: 5px; padding-right: 5px;"|Eden
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{no}}
|{{no}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v5|Version 5]] / [[/v6|6]]
|style="padding-left: 5px; padding-right: 5px;"|pre-12 / 12.0
|style="padding-left: 5px; padding-right: 5px;"|Frodo
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|style="padding-left: 5px; padding-right: 5px;"|[[/v6|Version 6]]
|style="padding-left: 5px; padding-right: 5px;"|13.0
|style="padding-left: 5px; padding-right: 5px;"|Gotham
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}

|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|{{yes}}
|-
|}

== Documentation ==
XBMC's JSON-RPC API has been designed to be self-documented i.e. a call to [[/v3#JSONRPC.Introspect|JSONRPC.Introspect]] results in a JSON-RPC response containing a documentation for all the available methods and data types. While this documentation is very incomplete and partly wrong for [[/v3|version 2]] it is provided as a full [http://tools.ietf.org/html/draft-zyp-json-schema-03 JSON schema] starting with [[/v3|version 3]]. As the documentation retrieved in that way is always specific to the used version of XBMC, it is (especially for development versions) the best documentation available and should be preferred over the wiki documentation as the latter always documents the API of the latest development.

== 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
<syntaxhighlight lang="xml" enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
</jsonrpc>
</syntaxhighlight>
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 ===
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 [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. {{see also|SSH}}

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

== See also ==
* [[/v2|JSON-RPC API v2 (Dharma)]]
* [[/v4|JSON-RPC API v4 (Eden)]]
* [[/v6|JSON-RPC API v6 (Frodo)]]

== 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)]

== Examples ==
These examples take their base from v4. Any that require a higher version will be marked.

[[JSON-RPC_API/Examples]]

[[Category:XBMC Manual]]
[[Category:Development]]