116 lines
4.2 KiB
ReStructuredText
116 lines
4.2 KiB
ReStructuredText
.. _http-api:
|
|
|
|
*****************
|
|
HTTP JSON-RPC API
|
|
*****************
|
|
|
|
.. module:: mopidy.http
|
|
:synopsis: The HTTP frontend APIs
|
|
|
|
The :ref:`ext-http` extension makes Mopidy's :ref:`core-api` available using
|
|
JSON-RPC over HTTP using HTTP POST and WebSockets. We also provide a JavaScript
|
|
wrapper, called :ref:`Mopidy.js <mopidy-js>`, around the JSON-RPC over
|
|
WebSocket API for use both from browsers and Node.js. The
|
|
:ref:`http-explore-extension` extension, can also be used to get you
|
|
familiarized with HTTP based APIs.
|
|
|
|
.. warning:: API stability
|
|
|
|
Since the HTTP JSON-RPC API exposes our internal core API directly it is to
|
|
be regarded as **experimental**. We cannot promise to keep any form of
|
|
backwards compatibility between releases as we will need to change the core
|
|
API while working out how to support new use cases. Thus, if you use this
|
|
API, you must expect to do small adjustments to your client for every
|
|
release of Mopidy.
|
|
|
|
From Mopidy 1.0 and onwards, we intend to keep the core API far more
|
|
stable.
|
|
|
|
|
|
.. _http-post-api:
|
|
|
|
HTTP POST API
|
|
=============
|
|
|
|
The Mopidy web server accepts HTTP requests with the POST method to
|
|
http://localhost:6680/mopidy/rpc, where the ``localhost:6680`` part will vary
|
|
with your local setup. The HTTP POST endpoint gives you access to Mopidy's
|
|
full core API, but does not give you notification on events. If you need
|
|
to listen to events, you should probably use the WebSocket API instead.
|
|
|
|
Example usage from the command line::
|
|
|
|
$ curl -d '{"jsonrpc": "2.0", "id": 1, "method": "core.playback.get_state"}' http://localhost:6680/mopidy/rpc
|
|
{"jsonrpc": "2.0", "id": 1, "result": "stopped"}
|
|
|
|
For details on the request and response format, see :ref:`json-rpc`.
|
|
|
|
|
|
.. _websocket-api:
|
|
|
|
WebSocket API
|
|
=============
|
|
|
|
The Mopidy web server exposes a WebSocket at http://localhost:6680/mopidy/ws,
|
|
where the ``localhost:6680`` part will vary with your local setup. The
|
|
WebSocket gives you access to Mopidy's full API and enables Mopidy to instantly
|
|
push events to the client, as they happen.
|
|
|
|
On the WebSocket we send two different kind of messages: The client can send
|
|
:ref:`JSON-RPC 2.0 requests <json-rpc>`, and the server will respond with
|
|
JSON-RPC 2.0 responses. In addition, the server will send :ref:`event messages
|
|
<json-events>` when something happens on the server. Both message types are
|
|
encoded as JSON objects.
|
|
|
|
If you're using the API from JavaScript, either in the browser or in Node.js,
|
|
you should use :ref:`mopidy-js` which wraps the WebSocket API in a nice
|
|
JavaScript API.
|
|
|
|
|
|
.. _json-rpc:
|
|
|
|
JSON-RPC 2.0 messages
|
|
=====================
|
|
|
|
JSON-RPC 2.0 messages can be recognized by checking for the key named
|
|
``jsonrpc`` with the string value ``2.0``. For details on the messaging format,
|
|
please refer to the `JSON-RPC 2.0 spec
|
|
<http://www.jsonrpc.org/specification>`_.
|
|
|
|
All methods (not attributes) in the :ref:`core-api` is made available through
|
|
JSON-RPC calls over the WebSocket. For example,
|
|
:meth:`mopidy.core.PlaybackController.play` is available as the JSON-RPC method
|
|
``core.playback.play``.
|
|
|
|
The core API's attributes is made available through setters and getters. For
|
|
example, the attribute :attr:`mopidy.core.PlaybackController.current_track` is
|
|
available as the JSON-RPC method ``core.playback.get_current_track``.
|
|
|
|
Example JSON-RPC request::
|
|
|
|
{"jsonrpc": "2.0", "id": 1, "method": "core.playback.get_current_track"}
|
|
|
|
Example JSON-RPC response::
|
|
|
|
{"jsonrpc": "2.0", "id": 1, "result": {"__model__": "Track", "...": "..."}}
|
|
|
|
The JSON-RPC method ``core.describe`` returns a data structure describing all
|
|
available methods. If you're unsure how the core API maps to JSON-RPC, having a
|
|
look at the ``core.describe`` response can be helpful.
|
|
|
|
|
|
.. _json-events:
|
|
|
|
Event messages
|
|
==============
|
|
|
|
Event objects will always have a key named ``event`` whose value is the event
|
|
type. Depending on the event type, the event may include additional fields for
|
|
related data. The events maps directly to the :class:`mopidy.core.CoreListener`
|
|
API. Refer to the :class:`~mopidy.core.CoreListener` method names is the
|
|
available event types. The :class:`~mopidy.core.CoreListener` method's keyword
|
|
arguments are all included as extra fields on the event objects. Example event
|
|
message::
|
|
|
|
{"event": "track_playback_started", "track": {...}}
|