Getting started

The Applications API was created so that applications are being managed by the RAIL and allows other (third-party) apps to add actions in a way that control can perform these actions and change settings.

How it’s done is by using the android broadcast system. It will send out a broadcast when the RAIL (re)starts or if an app has been installed and will ask to register it’s applications to the RAIL.

This section describes how you can add, get and remove applications from the Applications API.
Every publish message has a key, which is a String based ID to create a unique message.

To establish a link between the application, and the implemented settings associated with this application (via Settings API), the application id must match the category_id of the settings.

Get category

A category is needed when wanting to registrate a new application to the Applications API. Categories are used to seperate specific applications from eachother and are categorized in the Apps & Config page in ZBOS Control.

Support to add your custom category will be added in the future.

Publish topic

zbos/applications/categories/get

Payload example

fetches all categories.

{"key":"d66232"}

Result

[
  {
    "id": "zbos",
    "name_key": "default.app_category_title_zbos",
    "weight": 10
  },
  {
    "id": "apps",
    "name_key": "default.app_category_title_apps",
    "weight": 20
  }
]

Add application

An application is used to display settings and can perform an action in the RAIL, external apps and ZBOS Control itself. This action can be defined by adding an action to the actions list. Where the action needs to be performed will be differentiated by the action type.

Action types: OPEN, // Will be handled in the RAIL
OPEN_CONTROL, // Will be handled in the control
SETTINGS, // Will be handled in the control: setting for the app
DATASOURCES, // Will be handled in the control: only used for Zora atm
OTHER // Will be handled by the app itself: publish MQTT message & listen in app

Publish topic

zbos/applications/registration/add

Payload example

In this payload example, the Translation API is used to register the actual name_key value. Where default from default.pref_header_base_application is the category defined in the Translations API.

You can also see that the application id is base_application. When you want to link this to settings created by the settings API, this application id must be equal to the category from the created settings.

{
  "key": "93cf41",
  "application": {
    "id": "base_application",
    "name_key": "default.pref_header_base_application",
    "category_id": "apps",
    "weight": 1,
    "actions": [
      {
        "application_id": "base_application",
        "name_key": "default.app_action_settings",
        "type": "settings"
      },
      {
        "application_id": "base_application",
        "name_key": "default.app_action_start_action",
        "type": "other"
      }
    ]
  }
}

Result

{"success":true} // true if succeeded, false if failed

Get application

Introduction

Retrieving applications can be done in 2 ways. With the use of filters or without which will return all the registered applications. There is also a possibility to define a limit of how many applications you want to retrieve to shrink the payload size.

Filter types: id
name_key
category_id
weight
actions

Publish topic

zbos/applications/apps/get

Payload example 1

Fetch all applications.

{
  "key": "b69f36",
}

Payload example 2

Fetch all applications with optional filters.

{
  "key": "b69f36",
  "limit": 20,
  "offset": 0,
  "filters": [
    {
      "field": "category_id",
      "value": "base_application"
    }
  ],
  "language": "en-US",
}

Result

[
  {
    "id": "base_application",
    "name_key": "default.pref_header_base_application",
    "category_id": "apps",
    "weight": 1,
    "actions": [
      {
        "application_id": "base_application",
        "name_key": "default.app_action_settings",
        "type": "settings"
      },
      {
        "application_id": "base_application",
        "name_key": "default.app_action_start_action",
        "type": "other"
      }
    ]
  }
]

Remove application

Introduction

Publish topic

zbos/applications/registration/remove

Payload example

{
  "key": "14fa53", // String based ID
  "id": "base_application"
}

Result

{"success":true} // true if succeeded, false if failed

Start application action

Subscribe topic

zbos/applications/actions/start

Result

{
  "application_id": "base_application",
  "name_key": "default.app_action_start_action",
  "type": "other",
  "data": {}
}

Publish topic

zbos/applications/actions/start/response/{key}

Payload example

{"success":true} // true if succeeded, false if failed

Get application icons

Publish topic

zbos/applications/icons/get

Payload example

{
  "key": "49fe3f",
  "max_width": 100, // optional, can be used to decrease payload size
  "max_height": 100, // optional, can be used to decrease payload size
  "application_id": "base_application"
}

Result

{
  "application_id": "base_application",
  "icon": "{base64image}"
}