XBMC will be renamed to Kodi for v14. Read here for more details
Various pages on the wiki might contain old references to "XBMC", but will most often still apply to "Kodi". Find out how you can help here.

JSON-RPC API, Help:Main page

From Kodi
(Difference between pages)
Jump to: navigation, search
(added version comparison table)
 
 
Line 1: Line 1:
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].
+
{{divbox|orange||To edit the XBMC Wiki just register for an account. Page creation and editing of certain pages requires an account that is a few days old and has made a hand full of edits. If you have any questions about editing or access to the XBMC Wiki, please leave a message on [[Talk:Main Page]] or contact ned (at) nedscott (dot) com .}}
 +
:''See also: '''[[XBMC:Proposed wiki structure]]'''''
  
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.
+
This is for help with editing the XBMC Wiki. For help with XBMC Media Center, please see [[XBMC Online Manual]].
  
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.
+
==Wiki editing 101==
 +
Here's some wiki editing 101 links from Wikipedia. Most things that work on Wikipedia should also work on the XBMC Wiki. If you see a feature or template on Wikipedia that you would like to use here then let us know on [[Talk:Main Page]] or contact ned (at) nedscott (dot) com .
 +
*[[mw:Help:Editing pages]]
 +
*[[w:Help:Contents/Editing Wikipedia]]
 +
*[[w:Wikipedia:FAQ/Editing]]
 +
*[[w:Wikipedia:Cheatsheet]]
  
==Enabling JSON-RPC==
+
==Tools==
Since the interface is available on many transports enabling it depends on the transport.
+
*'''[[:Category:Templates]]-''' formatting and message templates that you can use on pages for various things.  
* Python: Always enabled
+
*'''Gadgets-''' Go to the top of any page and click on "My preferences -> Gadgets" and check out some of the additional editing tools there, especially the '''wikEd''' option
* HTTP: In System/Settings/Network/Services activate ''Allow control of XBMC via HTTP''
+
*'''[[Special:SpecialPages]]''' contains a number of tools and reports to help with editing.
* 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
+
*Some additional functions on this wiki are documented via links at '''[[Special:Version]]'''.
 +
*'''YouTube-''' To embed youtube videos (XBMC related videos only!) use <code><nowiki>{{youtube|ID}}</nowiki></code> where id= is the YouTube ID from the URL. For example, <code><nowiki>{{youtube|4NR57ELY28s}}</nowiki></code>. You can also define |height= and |width= (default is 569x320).
 +
*'''Like/PlusOne-''' Add a Facebook '''Like''' or a Google '''PlusOne''' to a specific wiki page, ether in reference to the page itself or the topic the page is about. The tags are: {{tl|Like}}, {{tl|Recommend}}, {{tl|PlusOne}}. Click on their links for more info.
  
Note: The EventServer is a different interface for sending remote keypresses to XBMC, and must be enabled separately, some programs may use both interfaces.
+
==Types of pages==
 +
*'''General topics (main namespace)'''- Anything that is a general overview of a topic. This can be main manual pages, a page for a remote control, a page for a specific hardware part, a supplemental tool/program, or just about anything XBMC related. Some pages might be a manual-type page explaining something in XBMC, or it could be something just XBMC-related and just serving as a basic info page + bookmarks.
 +
*'''XBMC Manual'''- Core XBMC manual/help pages. Can be in several namespaces. See [[:Category:XBMC Manual]]
 +
*'''FAQs'''- Question/common topic and answers. See [[:Category:FAQ]] and [[Template:FAQ]]
 +
*'''HOW-TO:'''- How-to's some manual pages will simply be both general pages and a how-to page, or be paired with a how-to page. Pages in the ''HOW-TO:'' namespace should be just just for step-by-step how to's. For how-to's within a general topic page, just use the main namespace. Some how-to's are apart of the main manual, and others are more specific. We welcome any how-to's that people feel would be useful. See [[:Category:How-to]].
 +
*'''Add-ons:'''- Add-ons, skins, etc. Great for Add-on developers and users alike. See [[:Category:All add-ons]]. '''Examples of good add-on pages include: [[Add-on:YouTube]], [[Add-on:BlipTV]], [[Add-on:iPlayer]], [[Add-on:PleXBMC]], [[Add-on:Common plugin cache]]'''. Subpages (if needed) can be made with a slash ('''/''') in the name.
 +
*'''Development'''- Pages for developers or really advanced topics. Includes Skin and Add-on development. Can be in several namespaces. See [[:Category:Development]]
 +
*'''User:'''- Username space for user pages. All editors get their own User page and can make additional subpages by adding a slash ('''/'''). Great for putting down notes on what you are working on for the XBMC Wiki, or you can even use your userpage to document your own XBMC set ups.
  
==Transports==
+
==Where we need help==
===Functionalities===
+
''everywhere, but here's an easy list:''
TODO
+
*All of the FAQs, see [[:Category:FAQ]]
 +
**An upgrading to v11 (Eden) FAQ for changes, what to expect, where to find things that moved, the file/library mode thing, etc. See [[Upgrading to XBMC v11]] for a pre-created page.
 +
*Improve [[Quick Start Guide]]
 +
*Update screen shots on various pages (click on an image and then click on "upload new version")
 +
*Wiki How-tos for:
 +
**Bluray stuff
 +
**3D stuff
 +
*Screen shots uploaded for all skins in [[:Category:Skins]]
 +
**Any other kind of manual/help info specific to skins
 +
*Expanding Add-on pages. Great for Add-on developers and users alike. See [[:Category:All add-ons]].
  
===Comparison===
+
: '''Examples of good add-on pages include:
The following table shows all the available transports and what functionalities they support
+
:* [[Add-on:YouTube]]
{| class="wikitable" style="margin-right: 0;"
+
:* [[Add-on:BlipTV]]
!style="padding-left: 5px; padding-right: 10px;"|Transport
+
:* [[Add-on:iPlayer]]
!style="padding-left: 10px; padding-right: 10px;"|Response
+
:* [[Add-on:PleXBMC]]
!style="padding-left: 10px; padding-right: 10px;"|Notifications
+
:* [[Add-on:Common plugin cache]]
!style="padding-left: 10px; padding-right: 10px;"|Direct file<br />download
+
:* [[Add-on:Artwork Downloader]]
!style="padding-left: 10px; padding-right: 10px;"|Redirected file<br />download
+
: Subpages (if needed) can be made with a slash ('''/''') in the name.
|-
+
*Pages/writeups for:
|style="padding-left: 5px;"|[[Python Development|Python]]
+
**A list of iOS remote apps
|{{yes}}
+
**[[Troubleshooting]]
|{{yes}}
+
*Spel cheking (everywhere)
|{{no}}
+
*Useful keymaps. See [[:Category:Custom keymaps]]
|{{no}}
+
*Spam/vandalism patrolling of '''[http://wiki.xbmc.org/index.php?title=Special:RecentChanges&hidepatrolled=1 unpatrolled edits]'''. See spam? Remove it! You can use the Undo feature or find a spam-free version in the "View history" tab (click on a past version, then click on Edit, then save, to restore an older version of a page).
|-
+
*Pages needing updating/cleaning up: [[:Category:Cleanup]]
|style="padding-left: 5px;"|[http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP]
+
*Pages needing expanding: [[:Category:Incomplete]]
|{{yes}}
+
*XBMC Wiki help pages (including this very page). Need expanding, how-to's, etc, on how to edit and use the XBMC Wiki.
|{{yes}}
+
|{{no}}
+
|{{no}}
+
|-
+
|style="padding-left: 5px;"|[http://en.wikipedia.org/wiki/HTTP HTTP]
+
|{{yes}}
+
|{{no}}
+
|{{no}}
+
|{{yes}}
+
|-
+
|}
+
  
==API versions==
+
[[Category:Wiki]]
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:
+
* [[/v2|JSON-RPC v2 (Dharma)]]
+
* [[/v3|JSON-RPC v3 (pre Eden)]]
+
 
+
===Comparison (JSON-RPC 2.0 compatibility)===
+
{| class="wikitable" style="margin-right: 0;"
+
!style="padding-left: 5px; width: 7em; text-align: left;"|Version
+
!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;"|Bulk requests
+
|-
+
|style="padding-left: 5px;"|[[/v2|Version 2]]
+
|{{yes}}
+
|{{yes}}
+
|{{no}}
+
|{{yes}}
+
|{{no}}
+
|{{no}}
+
|-
+
|style="padding-left: 5px;"|[[/v3|Version 3]]
+
|{{yes}}
+
|{{yes}}
+
|{{yes}}
+
|{{yes}}
+
|{{yes}}
+
|{{yes}}
+
|-
+
|}
+
 
+
==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
+
<source lang="xml">
+
<jsonrpc>
+
    <compactoutput>false</compactoutput>
+
</jsonrpc>
+
</source>
+
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.
+
 
+
====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.
+
 
+
==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:Development]]
+

Revision as of 18:21, 3 March 2012

See also: XBMC:Proposed wiki structure

This is for help with editing the XBMC Wiki. For help with XBMC Media Center, please see XBMC Online Manual.

Contents

1 Wiki editing 101

Here's some wiki editing 101 links from Wikipedia. Most things that work on Wikipedia should also work on the XBMC Wiki. If you see a feature or template on Wikipedia that you would like to use here then let us know on Talk:Main Page or contact ned (at) nedscott (dot) com .

2 Tools

  • Category:Templates- formatting and message templates that you can use on pages for various things.
  • Gadgets- Go to the top of any page and click on "My preferences -> Gadgets" and check out some of the additional editing tools there, especially the wikEd option
  • Special:SpecialPages contains a number of tools and reports to help with editing.
  • Some additional functions on this wiki are documented via links at Special:Version.
  • YouTube- To embed youtube videos (XBMC related videos only!) use {{youtube|ID}} where id= is the YouTube ID from the URL. For example, {{youtube|4NR57ELY28s}}. You can also define |height= and |width= (default is 569x320).
  • Like/PlusOne- Add a Facebook Like or a Google PlusOne to a specific wiki page, ether in reference to the page itself or the topic the page is about. The tags are: {{Like}}, {{Recommend}}, {{PlusOne}}. Click on their links for more info.

3 Types of pages

  • General topics (main namespace)- Anything that is a general overview of a topic. This can be main manual pages, a page for a remote control, a page for a specific hardware part, a supplemental tool/program, or just about anything XBMC related. Some pages might be a manual-type page explaining something in XBMC, or it could be something just XBMC-related and just serving as a basic info page + bookmarks.
  • XBMC Manual- Core XBMC manual/help pages. Can be in several namespaces. See Category:XBMC Manual
  • FAQs- Question/common topic and answers. See Category:FAQ and Template:FAQ
  • HOW-TO:- How-to's some manual pages will simply be both general pages and a how-to page, or be paired with a how-to page. Pages in the HOW-TO: namespace should be just just for step-by-step how to's. For how-to's within a general topic page, just use the main namespace. Some how-to's are apart of the main manual, and others are more specific. We welcome any how-to's that people feel would be useful. See Category:How-to.
  • Add-ons:- Add-ons, skins, etc. Great for Add-on developers and users alike. See Category:All add-ons. Examples of good add-on pages include: Add-on:YouTube, Add-on:BlipTV, Add-on:iPlayer, Add-on:PleXBMC, Add-on:Common plugin cache. Subpages (if needed) can be made with a slash (/) in the name.
  • Development- Pages for developers or really advanced topics. Includes Skin and Add-on development. Can be in several namespaces. See Category:Development
  • User:- Username space for user pages. All editors get their own User page and can make additional subpages by adding a slash (/). Great for putting down notes on what you are working on for the XBMC Wiki, or you can even use your userpage to document your own XBMC set ups.

4 Where we need help

everywhere, but here's an easy list:

  • All of the FAQs, see Category:FAQ
    • An upgrading to v11 (Eden) FAQ for changes, what to expect, where to find things that moved, the file/library mode thing, etc. See Upgrading to XBMC v11 for a pre-created page.
  • Improve Quick Start Guide
  • Update screen shots on various pages (click on an image and then click on "upload new version")
  • Wiki How-tos for:
    • Bluray stuff
    • 3D stuff
  • Screen shots uploaded for all skins in Category:Skins
    • Any other kind of manual/help info specific to skins
  • Expanding Add-on pages. Great for Add-on developers and users alike. See Category:All add-ons.
Examples of good add-on pages include:
Subpages (if needed) can be made with a slash (/) in the name.
  • Pages/writeups for:
  • Spel cheking (everywhere)
  • Useful keymaps. See Category:Custom keymaps
  • Spam/vandalism patrolling of unpatrolled edits. See spam? Remove it! You can use the Undo feature or find a spam-free version in the "View history" tab (click on a past version, then click on Edit, then save, to restore an older version of a page).
  • Pages needing updating/cleaning up: Category:Cleanup
  • Pages needing expanding: Category:Incomplete
  • XBMC Wiki help pages (including this very page). Need expanding, how-to's, etc, on how to edit and use the XBMC Wiki.
Personal tools
Namespaces

Variants
Actions
Navigation
Wiki help
Toolbox