|
|
The HTTP API can be used by external applications or web pages to communicate with OpenLP.
|
|
|
|
|
|
To know what the state of OpenLP is and when it changes, you should use the [WebSockets server](websockets).
|
|
|
|
|
|
# API versions
|
|
|
|
|
|
OpenLP 3.x.x Supports both the first version of the API (v1), and the second version of the API (v2). The first version of the API is depreciated and may be removed in a future version of OpenLP.
|
|
|
|
|
|
This document outlines the prefered version of the API (v2).
|
|
|
|
|
|
# Getting Started
|
|
|
|
|
|
OpenLP runs the API server on the same port as the OpenLP remote. This is port `4316` by default. To use the API, use the host name of the computer OpenLP is running on, and the port assigned to the web server (`4316` by default). All endpoints in the v2 api are prefixed with `/api/v2`.
|
|
|
|
|
|
For example, if OpenLP is running on a computer with the local IP `192.168.1.23`, then we can get a image of the live display by heading to the url: `http://192.168.1.23:4316/api/v2/live-image`
|
|
|
|
|
|
> **Note**
|
|
|
>
|
|
|
> The OpenLP server is only available on your local network. OpenLP does not perform any sort of port forwarding and the server is not capable of handling large loads. It is not recommended to expose the OpenLP server to the internet unless you know what you are doing.
|
|
|
|
|
|
|
|
|
# Authentication
|
|
|
|
|
|
Some endpoints require authentication if a username and password has been added in the settings. To authenticate your application, send a [`POST` request to `/api/v2/core/login`](#corelogin-post) with a JSON body containing the `username` and `password`. That will return the authentication token which you need to put in your request header: `Authorization: <authentication_token>`.
|
|
|
|
|
|
A endpoint that requires you to have been authenticated (if enabled) is marked with a `🔒` icon.
|
|
|
|
|
|
# Endpoints
|
|
|
|
|
|
All responses are in JSON format. To describe the structure of a JSON response, you'll see a tree view. A JSON response can contain any JSON data type, including <mark>[ ]</mark> JSON array, <mark>{ }</mark> JSON object, <mark>St</mark> JSON string, <mark>TF</mark> JSON boolean and <mark>Nm</mark> JSON number.
|
|
|
|
|
|
The API endpoints are split into 4 categories:
|
|
|
1. [Controller](#controller) - View and control the live service item and themes
|
|
|
2. [Core](#core) - Show/hide display, login and other info
|
|
|
3. [Plugins](#plugins) - Search and add service items
|
|
|
4. [Service](#service) - View and control the current service
|
|
|
|
|
|
## Controller
|
|
|
|
|
|
The controller endpoints provide information about the live service item and theme information. It also allows changing slide and changing the theme.
|
|
|
|
|
|
#### `/controller/live-items` `GET`
|
|
|
Returns details about the live service item.
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments: *N/A*
|
|
|
- <details><summary>Show Return Format</summary>
|
|
|
<pre>
|
|
|
<mark>{}</mark> - Root of the response
|
|
|
├── <mark>[]</mark> <b>audit:</b> - List of legal information about the service item
|
|
|
│ └── The strings are always in this order:
|
|
|
│ [<title>, <authors_all>, <copyright>, <ccli_number>]
|
|
|
├── <mark>[]</mark> <b>backgroundAudio:</b> - List of audio files.
|
|
|
├── <mark>[]</mark> <b>capabilities:</b> - List of capabilities (number indexes).
|
|
|
├── <mark>{}</mark> <b>data:</b> - The data associated with the service item.
|
|
|
│ └── This can contain anything but most commonly contains these attributes:
|
|
|
│ "alternate_title", "authors", "ccli_number", "copyright", "title"
|
|
|
├── <mark>[]</mark> <b>footer:</b> - Footer strings, line by line.
|
|
|
├── <mark>TF</mark> <b>fromPlugin:</b> - If this service item came from a plugin.
|
|
|
├── <mark>TF</mark> <b>isThemeOverwritten:</b> - If this item provides it's own theme.
|
|
|
├── <mark>St</mark> <b>name:</b> - The name of the plugin that created this service item.
|
|
|
├── <mark>St</mark> <b>notes:</b> - Notes for this service item.
|
|
|
├── <mark>[]</mark> <b>slides:</b> - Slide data for this service item.
|
|
|
│ └── <mark>{}</mark> - A slide list item
|
|
|
│ ├── <mark>St</mark> <b>chords:</b> HTML formatted string containing chords.
|
|
|
│ ├── <mark>St</mark> <b>footer:</b> HTML formatted footer text for this slide.
|
|
|
│ ├── <mark>St</mark> <b>html:</b> HTML formatted slide with no chords.
|
|
|
│ ├── <mark>St</mark> <b>text:</b> Plain text slide with no chords.
|
|
|
│ ├── <mark>TF</mark> <b>selected:</b> If this is the selected slide.
|
|
|
│ ├── <mark>St</mark> <b>tag:</b> The tag used to identify this verse.
|
|
|
│ ├── <mark>St</mark> <b>tag:</b> The tag used to identify this verse.
|
|
|
│ └── <mark>St</mark> <b>title:</b> Same as the service item title.
|
|
|
├── <mark>St</mark> <b>theme:</b> - This service item's selected theme, null if missing.
|
|
|
├── <mark>St</mark> <b>title:</b> - Service item title.
|
|
|
└── <mark>St</mark> <b>type:</b> - Display type.
|
|
|
└── Can be one of the following:
|
|
|
"ServiceItemType.Text", "ServiceItemType.Image", "ServiceItemType.Command"</pre></details>
|
|
|
|
|
|
- Notes - Returns an empty object (`{}`) if there is no active service item.
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/live-item` `GET`
|
|
|
Returns details about the live item with only the active slide.
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments - *N/A*
|
|
|
- <details><summary>Show Return Format</summary>
|
|
|
<pre>
|
|
|
<mark>{}</mark> - Root of the response
|
|
|
├── <mark>[]</mark> <b>audit:</b> - List of legal information about the service item
|
|
|
│ └── The strings are always in this order:
|
|
|
│ [<title>, <authors_all>, <copyright>, <ccli_number>]
|
|
|
├── <mark>[]</mark> <b>backgroundAudio:</b> - List of audio files.
|
|
|
├── <mark>[]</mark> <b>capabilities:</b> - List of capabilities (number indexes).
|
|
|
├── <mark>{}</mark> <b>data:</b> - The data associated with the service item.
|
|
|
│ └── This can contain anything but most commonly contains these attributes:
|
|
|
│ "alternate_title", "authors", "ccli_number", "copyright", "title"
|
|
|
├── <mark>[]</mark> <b>footer:</b> - Footer strings, line by line.
|
|
|
├── <mark>TF</mark> <b>fromPlugin:</b> - If this service item came from a plugin.
|
|
|
├── <mark>TF</mark> <b>isThemeOverwritten:</b> - If this item provides it's own theme.
|
|
|
├── <mark>St</mark> <b>name:</b> - The name of the plugin that created this service item.
|
|
|
├── <mark>St</mark> <b>notes:</b> - Notes for this service item.
|
|
|
├── <mark>[]</mark> <b>slides:</b> - Array contains one slide (the selected slide).
|
|
|
│ └── <mark>{}</mark> - A slide list item
|
|
|
│ ├── <mark>St</mark> <b>chords:</b> HTML formatted string containing chords.
|
|
|
│ ├── <mark>St</mark> <b>footer:</b> HTML formatted footer text for this slide.
|
|
|
│ ├── <mark>St</mark> <b>html:</b> HTML formatted slide with no chords.
|
|
|
│ ├── <mark>St</mark> <b>text:</b> Plain text slide with no chords.
|
|
|
│ ├── <mark>TF</mark> <b>selected:</b> If this is the selected slide.
|
|
|
│ ├── <mark>St</mark> <b>tag:</b> The tag used to identify this verse.
|
|
|
│ ├── <mark>St</mark> <b>tag:</b> The tag used to identify this verse.
|
|
|
│ └── <mark>St</mark> <b>title:</b> Same as the service item title.
|
|
|
├── <mark>St</mark> <b>theme:</b> - This service item's selected theme, null if missing.
|
|
|
├── <mark>St</mark> <b>title:</b> - Service item title.
|
|
|
└── <mark>St</mark> <b>type:</b> - Display type.
|
|
|
└── Can be one of the following:
|
|
|
"ServiceItemType.Text", "ServiceItemType.Image", "ServiceItemType.Command"</pre></details>
|
|
|
|
|
|
- Notes - Returns an empty object (`{}`) if there is no active service item.
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/show` `POST` `🔒`
|
|
|
Go to the specified slide
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *id* - The index of the slide to switch to. (0 based index)
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Missing slide id - Status 400 (BAD REQUEST)
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/progress` `POST` `🔒`
|
|
|
Go to the specified slide
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *action* - Slide switch direction, either `next` or `previous`.
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Missing slide *action* - Status 400 (BAD REQUEST)
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/theme-level` `GET` `🔒`
|
|
|
Get the theme level
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments - *N/A*
|
|
|
- Returns
|
|
|
- Status 200, returns a string, `global`, `service` or `song`.
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/theme-level` `POST` `🔒`
|
|
|
Set the theme level
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *level* - New theme level, either `global`, `service` or `song`.
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Missing *level* - Status 400 (BAD REQUEST)
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/themes` `GET`
|
|
|
Get a list of all themes
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments - *N/A*
|
|
|
- Return Format
|
|
|
<pre>
|
|
|
<mark>[]</mark> - Root of the response, list of themes
|
|
|
└── <mark>{}</mark> - A theme
|
|
|
├── <mark>St</mark> <b>name:</b> - The theme name.
|
|
|
├── <mark>TF</mark> <b>selected:</b> - If this is the selected theme (dependant on theme level).
|
|
|
└── <mark>St</mark> <b>thumbnail:</b> - Base64 thumbnail encoded in a unicode string.</pre>
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/themes/<theme_name>` `GET`
|
|
|
Get a theme's data
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *theme_name* (in url) - The name of a theme.
|
|
|
- Returns
|
|
|
- Status 200, returns theme's JSON data but file paths have been removed and `background_filename` now contains a css background string.
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/live-theme` `GET`
|
|
|
Get the live theme's data
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments - *N/A*
|
|
|
- Returns
|
|
|
- Status 200, returns live theme's JSON data but file paths have been removed and `background_filename` now contains a css background string.
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/theme` `GET`
|
|
|
Get the name of the current theme
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments - *N/A*
|
|
|
- Returns
|
|
|
- Status 200, returns current theme's name as a string.
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/theme` `POST` `🔒`
|
|
|
Sets the current theme
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *theme* - The name of a theme.
|
|
|
- Returns
|
|
|
- Status 200, returns current theme's name as a string.
|
|
|
- Notes
|
|
|
- If invalid theme name, the black default will be used.
|
|
|
- The request will set the theme at the current theme level.
|
|
|
- Setting the theme at song level is not implemented and returns a 501.
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/controller/clear/<controller>` `🔒`
|
|
|
Clears a controller
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *controller* (in url) - The name of the controller, only accepts `live` or `preview`.
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Invalid *controller* - Status 404 (NOT FOUND)
|
|
|
- Notes
|
|
|
- Only clears the controller itself, the live display will not change.
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
## Core
|
|
|
|
|
|
The core endpoints allow setting the display mode (show/hide), the login endpoint, a capture of the live display and information about OpenLP.
|
|
|
|
|
|
#### `/core/display` `POST` `🔒`
|
|
|
Displays or hides the live view
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *display* - A live view display mode. Can be one of these strings: `hide`, `show`, `blank`, `theme` or `desktop`.
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Invalid *display* - Status 400 (BAD REQUEST)
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/core/plugins` `GET`
|
|
|
Get list of plugins that provide a search function
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments - *N/A*
|
|
|
- Return Format
|
|
|
<pre>
|
|
|
<mark>[]</mark> - Root of the response, list of plugins
|
|
|
└── <mark>{}</mark> - A plugin
|
|
|
├── <mark>St</mark> <b>key:</b> - The plugin's identification name.
|
|
|
└── <mark>St</mark> <b>name:</b> - The plugin's name.</pre>
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/core/system` `GET`
|
|
|
Gets information about OpenLP API system settings
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments - *N/A*
|
|
|
- Return Format
|
|
|
<pre>
|
|
|
<mark>[]</mark> - Root of the response
|
|
|
└── <mark>{}</mark> - A plugin
|
|
|
├── <mark>TF</mark> <b>login_required:</b> - Is authentication required.
|
|
|
└── <mark>Nm</mark> <b>websocket_port:</b> - The websocket server port.</pre>
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/core/login` `POST`
|
|
|
Login to allow use of api endpoints that require authentication
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *username* - The server username
|
|
|
- *password* - The server password
|
|
|
- Returns
|
|
|
- On success - Status 200, format:
|
|
|
<pre>
|
|
|
<mark>{}</mark> - Root of the response
|
|
|
└── <mark>St</mark> <b>token:</b> - The server authentication token.</pre>
|
|
|
- Invalid login - Status 401 (Unauthorized)
|
|
|
- Missing request body - Status 400 (BAD REQUEST)
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/core/live-image` `GET`
|
|
|
Get a screenshot of the live display
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *username* - The server username
|
|
|
- *password* - The server password
|
|
|
- Return Format
|
|
|
<pre>
|
|
|
<mark>{}</mark> - A plugin
|
|
|
└── <mark>St</mark> <b>binary_image:</b> - Dispite the name, a unicode string is returned containing a base64 image (encoded in unicode).</pre>
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
## Plugins
|
|
|
|
|
|
The plugins endpoints provide some universal functions for all plugins that provide media items.
|
|
|
|
|
|
#### `/plugins/<plugin>/search?text=<search-phrase>` `GET` `🔒`
|
|
|
Search a plugin's available service items
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *plugin* (in url) - The target plugin.
|
|
|
- *search-phrase* (in url) - The string to search for.
|
|
|
- Returns
|
|
|
- Status 200, returns a list of results.
|
|
|
- Notes
|
|
|
- Relies on the plugins to provide results in the same format.
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/plugins/<plugin>/add` `POST` `🔒`
|
|
|
Add a service item to the service
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *plugin* (in url) - The target plugin.
|
|
|
- *id* - Id of a service item from the plugin.
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Invalid *id* - Status 400 (BAD REQUEST)
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/plugins/<plugin>/live` `POST` `🔒`
|
|
|
Send a plugin service item to the live controller
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *plugin* (in url) - The target plugin.
|
|
|
- *id* - Id of a service item from the plugin.
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Invalid *id* - Status 400 (BAD REQUEST)
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/plugins/<plugin>/search-options` `GET`
|
|
|
Get the available search options for a plugin
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *plugin* (in url) - The target plugin.
|
|
|
- Returns
|
|
|
- On success - Status 200, with search options in JSON format.
|
|
|
- Unsupported for plugin - Status 501 (NOT IMPLEMENTED)
|
|
|
- Notes
|
|
|
- Currently the only built in plugin that supports this is the bibles plugin.
|
|
|
- The bible plugin provides a bible specific API. It's return format is as follows:
|
|
|
<pre>
|
|
|
<mark>{}</mark> - The root
|
|
|
├── <mark>St</mark> <b>primary:</b> - The current primary bible name.
|
|
|
└── <mark>[]</mark> <b>bibles:</b> - A list of strings (bible names)</pre>
|
|
|
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/plugins/<plugin>/search-options` `POST` `🔒`
|
|
|
Set a plugin's search options
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *plugin* (in url) - The target plugin.
|
|
|
- *option* - A search option for the plugin.
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Missing *option* - Status 400 (BAD REQUEST)
|
|
|
- Unsupported for plugin - Status 501 (NOT IMPLEMENTED)
|
|
|
- Notes
|
|
|
- Currently the only built in plugin that supports this is the bibles plugin
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
## Service
|
|
|
|
|
|
The service endpoints provide information and controls for the current service.
|
|
|
|
|
|
#### `/service/items` `GET`
|
|
|
List the service items in the service
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments - *N/A*
|
|
|
- Return Format
|
|
|
<pre>
|
|
|
<mark>[]</mark> - Root of the response, list of all the service items
|
|
|
└── <mark>{}</mark> - A service item
|
|
|
├── <mark>St</mark> <b>ccli_number:</b> - CCLI number, empty string if not applicable or missing.
|
|
|
├── <mark>St</mark> <b>id:</b> - Unique service item id.
|
|
|
├── <mark>TF</mark> <b>is_valid:</b> - False if a required file is missing.
|
|
|
├── <mark>St</mark> <b>notes:</b> - Notes for the service item.
|
|
|
├── <mark>St</mark> <b>plugin:</b> - The plugin that provides this service item.
|
|
|
├── <mark>TF</mark> <b>selected:</b> - If this service item is currently live.
|
|
|
└── <mark>St</mark> <b>title:</b> - The service item's title.</pre>
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/service/show` `POST` `🔒`
|
|
|
Show an item from the service
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *id* - Unique service item id.
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Missing *id* - Status 400 (BAD REQUEST)
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/service/progress` `POST` `🔒`
|
|
|
Progress to the next or previous service item
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments
|
|
|
- *action* - Service progress action, can be `next` or `previous`.
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Missing *action* - Status 400 (BAD REQUEST)
|
|
|
|
|
|
----
|
|
|
</details>
|
|
|
|
|
|
#### `/service/new` `GET` `🔒`
|
|
|
Create a new service
|
|
|
<details><summary>Details</summary>
|
|
|
|
|
|
----
|
|
|
|
|
|
- Arguments - *N/A*
|
|
|
- Returns
|
|
|
- On success - Status 204 (NO CONTENT)
|
|
|
- Notes
|
|
|
- Does not save the existing service.
|
|
|
|
|
|
----
|
|
|
</details> |
|
|
\ No newline at end of file |