OpenSong API

An application programming interface for OpenSong to provide access to the main functionality using an HTTP/REST approach.

OpenSong is an application for managing and projecting songs, lyrics and chords, scripture fragments, free text, images and videos. OpenSong is cross platform, but the support is limited to the platforms made available by the IDE, which at present covers MacOS, Windows and Linux.
There is an increased amount of request to make OpenSong available on other platforms, such as iOS, Android or mobile platforms in general. This requires a complete rewrite in another platform specific language, or a different approach: an API.

The OpenSong API provides access to the OpenSong core elements for information retrieval, or modifying status. This means that external applications can request for example status information, or control a presentation without requiring a port of the business logic of OpenSong onto a different platform.

An example of a method exposed by the OpenSong API is to retrieve the current status in XML form:
GET http://localhost:8080/status

All communication travels over HTTP, OpenSong itself is the server, by default running on port 8080. The API is an REST service. The commands are executed using GET and POST methods:

1. GET requests are used for status or data retrieval
2. POST requests are used for all commands that might change status

Replies generally consist of an XML document, with exception for specific actions, for example retrieving the current slide image, which will return a JPEG image.

An HTTP request has the following typical form: http://host:port/resource[/action[/identifier][/param1:value1[/paramN:valueN]]]

• host: identifies the machine running OpenSong, for example localhost
• port: specifies the port on which OpenSong is listening for requests, by default 8080
• resource: mandatory part of the request to select a resource that will handle actions if applicable
• action: an optional string specifying the action to be executed
• identifier: an optional value to select a specific item. The meaning and allowed type is dependent on the resource and action
• param1 .. paramN: an optional parameter name. If parameters apply is action specific. Order of parameters is not relevant.
• value1 .. valueN: an optional parameter value for param. Valid parameter values are action specific

A basic level of authentication is used. Generally, authentication is required for all POST requests. Most GET resuests do not require authentication. In case authentication is required, but no credentials are supplied, OpenSong will reply with an HTTP Basic Authentication request response.
OpenSong does not facilitate configuring multiple users and passwords. The authentication is handled by a single authentication key that is to be supplied in the Basic Authentication request header:

Authorization: Basic __base64_encoded_key__

The following resources are available:

Handling information in a running presentation.

This resources requires an action to be specified. Available actions:

• list: Get a list of the slides in the current presentation including slide generics (name, title, slude number).
  Method: GET.
  Identifier: not applicable.
  Parameters: not applicable.
• slide: Get the raw XML data of a slide.
  Method: GET.
  Identifier: slide item number as available in the XML provided by the action list
  Parameters: not applicable.
• slide_preview: Get preview image for slide. The dimensions of the preview equal the size of the preview on the presentation helper window. Response is a JPEG image.
  Method: GET.
  Identifier: slide item number as available in the XML provided by the action list
  Parameters: not applicable.
• slide_image: Get image for current slide. The dimensions of the image equal the size of the present window, which equal the dimensions of the projector screen. Response is a JPEG image.
  Method: GET.
  Identifier: not applicable
  Parameters: not applicable.
• next_slide: Move to next slide.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• previous_slide: Move to previous slide.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• first_slide: Move to first slide.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• last_slide: Move to last slide.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• next_section: Move to next section.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• previous_section: Move to previous section.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• jump_to_chorus: Jump to chorus within the current song (if applicable in the current song).
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• jump_to_bridge: Jump to bridge within the current song (if applicable in the current song).
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• jump_to_prechorus: Jump to pre-chorus within the current song (if applicable in the current song).
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• jump_to_tag: Jump to tag within the current song (if applicable in the current song).
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• close_presentation: End the current running presentation (without interactive user confirmation).
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• normal_screen: Switch (back) to normal screen display mode.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• toggle_black: Toggle black screen.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• toggle_white: Toggle white screen.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• toggle_hide: Toggle hiding the current slide contents.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• toggle_logo: Toggle logo display.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• toggle_freeze: Toggle freeze.
  Method: POST.
  Identifier: not applicable
  Parameters: not applicable
• alert: Shows alert on screen.
  Method: POST.
  Identifier: not applicable
  Parameter 1 (optional): message, value is the text message to be shown. When the parameter is absent, the currently showing alert (if any) will be removed.
  
• jump_to_verse_n: Jump to a specific verse within the current song (if applicable in the current song).
  Method: POST.
  Identifier: verse number
  Parameters: not applicable
• jump_to_song_n: Jump to song within the current set.
  Method: POST.
  Identifier: song index (first song has index 1)
  Parameters: not applicable
• insert_song: Adds a song to the current showing set.
  Method: POST.
  Identifier: name of the song
  Parameter 1: folder, value is the name of the folder to load the songs of.
  Parameter 2: position, value is the slide number after which the song is to be inserted. When 0, the song will be inserted as firs item in the set. When absent, the song we be added to the end of the set.
• insert_scripture: Adds a scripture to the current showing set.
  Method: POST.
  Identifier: t.b.d.
  Parameters: t.b.d.

Exchanging song related data.

This resources requires an action to be specified. Available actions:

• detail: returns the raw XML of a song.
  Method: GET.
  Identifier: name of the song.
  Parameter 1: folder, value is the name of the folder to load the songs of.
• folders: returns a list with the names of the available song folders.
  Method: GET.
  Identifier: not applicable.
  Parameters: not applicable
• list: returns a list with the names of all available songs.
  Method: GET.
  Identifier: not applicable.
  Parameter 1: folder, value is the name of the folder to load the songs of.
• load: load a song into OpenSong
  Method: POST.
  Identifier: name of the song.
  Parameter 1: folder, value is the name of the folder to load the songs of.
• present: start a new presentation using a song. Implies a load in case another or no song is loaded.
  Method: POST.
  Identifier: name of the song.
  Parameter 1: folder, value is the name of the folder to load the songs of.
  Parameter 2: display, parameter value determines the display mode where 1 is single display and 2 is dual display (launching presentation helper).
  Parameter 1 and Parameter 2 can be swapped and both are optional.

Exchanging set related data.

This resources requires an action to be specified. Available actions:

• list: returns a list with the names of all available sets.
  Method: GET.
  Identifier: not applicable.
  Parameters: not applicable
• list_slides: returns a list of all slides in a set. A short summary per slide will be returned. For full slide details, use slide_detail.
  Method: GET.
  Identifier: the name of the set.
  Parameters: not applicable
• load: load a set into OpenSong
  Method: POST.
  Identifier: the name of the set.
• slide_detail: returns the raw slide XML for one slide of the set. Method: GET.
  Identifier: the name of the set.
  Parameter 1: name: slide_index, parameter value is the index of the slide in the set where the first slide has index number 1.
• present: start a new presentation. Implies a load in case another or no set is loaded.
  Method: POST.
  Identifier: the name of the set.
  Parameter 1: name: slide_index, parameter value is the index of the slide in the set where the first slide has index number 1; omission of the parameter has the same effect as using slide_index=1.
  Parameter 2: display, parameter value determines the display mode where 1 is single display and 2 is dual display (launching presentation helper).
  Parameter 1 and Parameter 2 can be swapped and both are optional.

Provide a short overview of the OpenSong status.

This resources does not support actions.
Method: GET or POST.
The response always is an XML document of the following form:

<response>
  <presentation_active>1</presentation_active>
  <current_slide>
    <itemnumber>2</itemnumber>
    <name>no name</name>
    <title>no title</title>
  </current_slide>
</response>

The value of presentation_active is 1 or 0 depending on whether a presentation is running or not.
The child nodes of current_slide are only available in case of an active presentation.
Itemnumber is a unique identifier (numeric) of a slide in a set. This number is generated on launch of a presentation and will not change. Dynamically inserted slides will also have a unique number. The itemnumber is not a sequence number indicating the position of the slide in the set.

This resource provides access to the websocket interface. Using websockets enables bidirectional communication and status pushing from OpenSong to the client instead of polling.
To initiate a websocket session, connect the client to ws://host:port/ws.
The socket interface provides full interactive access to all resources by sending the regular URI request as text data to OpenSong:

resource[/action[/identifier][/param1:value1[/paramN:valueN]]]

The websocket implementation is basic and limited to sending complete data frames for text or binary data using the approve websocket specification RFC 6455. At present the implemented functionality is fully backwards compatible to draft hybi-10. Secure websockets (wss) are not supported.

Next to the normal resources, the ws resource provides the following actions:

• subscribe: Activates notifications for a specific topic, genarally identical to a resource name.
  Method: POST.
  Identifier: The name of the topic or resource, to be defined.
  Parameters: not applicable
• unsubscribe: Deactivates notifications for a specific topic, genarally identical to a resource name.
  Method: POST.
  Identifier: The name of the topic or resource, to be defined.
  Parameters: not applicable