balena-supervisor/docs/dependent-apps.md

# Using the balena Supervisor to manage dependent applications

Since version 2.5.0 the balena Supervisor can act as a proxy for dependent apps.

Only Supervisors after version 2.5.0 have this functionality, and some of the endpoints appeared in later versions (we've noted it down where this is the case).

## What is a dependent application

A **dependent application** is a balena application that targets devices not capable of interacting directly with the balena API - the reasons can be several, the most common are:

- no direct Internet capabilities
- not able to run balenaOS (being a microcontroller, for example)

The **dependent application** is scoped under a balena application, which gets the definition of **gateway application**.

The **gateway application** is responsible for detecting, provisioning and managing **dependent devices** belonging to one of its **dependent applications**. This is possible leveraging a new set of endpoints exposed by the balena Supervisor.

When a new version of the dependent application is git pushed, the supervisor will download the docker image and expose the assets in one of the endpoints detailed below. It is then the gateway application (i.e. the user app that is run by the supervisor) that is responsible for ensuring those assets get deployed to the dependent devices, using the provided endpoints to perform the management.

A dependent application follows the same development cycle of a conventional balena application:

- it binds to your git workspace via the **balena remote**
- it consists in a Docker application
- it offers the same environment and configuration variables management

There are some differences:

- it does not support Dockerfile templating
- the Dockerfile must target either an `x86` or `amd64` base image
- the actual firmware/business logic must be stored in the `/assets` folder within the built docker image.
  - You can either just `COPY` a pre-built artifact in that folder, or build your artifact at push time and then store it in the `/assets` folder.
- **a dependent application Docker image is only used to build, package and deliver the firmware on the dependent device via balena-supervisor - it won't be run at any point.**

## How a dependent application works

### Endpoints

The supervisor exposes a REST API to interact with the dependent applications and dependent devices models that come from the balena API - it also allows using a set of hooks to have push functionality, both documented below.

# HTTP API reference

## Applications

### GET /v1/dependent-apps
Dependent Applications List

**Example**

```bash
curl -X GET $BALENA_SUPERVISOR_ADDRESS/v1/dependent-apps?apikey=$BALENA_SUPERVISOR_API_KEY
```

**Response**
`HTTP/1.1 200 OK`

```javascript
[
     {
         "id": 13015,
         "name": "edgeApp1",
         "commit": "d43bea5e16658e653088ce4b9a91b6606c3c2a0d",
         "config": {}
     },
     {
         "id": 13016,
         "name": "edgeApp2",
         "commit": "d0f6624d6410fa079159fa3ebe0d3af46753d75d",
         "config": {}
     }
 ]
```

### GET /v1/dependent-apps/:appId/assets/:commit
Dependent Application Updates Registry

**Example**

```bash
curl -X GET $BALENA_SUPERVISOR_ADDRESS/v1/dependent-apps/<appId>/assets/<commit>?apikey=$BALENA_SUPERVISOR_API_KEY
```

**Response**
`HTTP/1.1 200 OK`


```none
[application/x-tar] .tar
```

## Devices

### GET /v1/devices
Dependent Devices List

**Example**

```bash
curl -X GET $BALENA_SUPERVISOR_ADDRESS/v1/devices?apikey=$BALENA_SUPERVISOR_API_KEY
```

**Response**
`HTTP/1.1 200 OK`


```javascript
[
     {
         "id": 1,
         "uuid": "5ae8cf6e062c033ea38435498ad9b487bcc714e9eab0fed0404ee56e397790",
         "appId": 13015,
         "device_type": "generic-amd64",
         "logs_channel": "69f961abffaad1ff66031b29f712be4fb19e1bfabf1fee7a9ebfb5fa75a1fbdb",
         "deviceId": "47270",
         "is_online": null,
         "name": "blue-sun",
         "status": "Provisioned",
         "download_progress": null,
         "commit": "d43bea5e16658e693088ce4b9a91b6606c3c2a0d",
         "targetCommit": "d43bea5e16653e653088ce4b9a91b6606c3c2a0d",
         "environment":{},
         "targetEnvironment":{},
         "config":{},
         "targetConfig":{"RESIN_SUPERVISOR_DELTA":"1"}
     },
     {
         "id": 3,
         "uuid": "8dc608765fd32665d49d218a7eb4657bc2ab8a56db06d2c57ef7c7e9a115da",
         "appId": 13015,
         "device_type": "generic-amd64",
         "logs_channel": "d0244a90e8cd6e9a1ab410d3d599dea7f15110a6fe37b2a8fd69bb6ee0bce043",
         "deviceId": "47318",
         "is_online": null,
         "name": "wild-paper",
         "status": "Provisioned",
         "download_progress": null,
         "commit": "d43bea5e16658e253088ce4b9a91b6606c3c2a0d",
         "targetCommit": "d43bea5e11658e653088ce4b9a91b6606c3c2a0d",
         "environment":{},
         "targetEnvironment":{},
         "config":{},
         "targetConfig":{"RESIN_SUPERVISOR_DELTA":"1"}
     }
 ]
```

### POST /v1/devices
Dependent Device Provision

The `device_type` parameter is optional, defaulting to `generic-amd64`. You
should only set this if you need to provision a dependent device to an
application with the deprecated `edge` device type.

**Example**

```bash
curl -H "Content-Type: application/json" -X POST --data '{"appId": <appId>,
"device_type": "edge"}' /
$BALENA_SUPERVISOR_ADDRESS/v1/devices?apikey=$BALENA_SUPERVISOR_API_KEY
```

**Response**
`HTTP/1.1 201 CREATED`


```javascript
{
          "id": 47318,
          "uuid": "8dc608765fd32665d49a268a7eb4657bc2ab8a56db06d2c57ef7c7e9a115da",
          "name": "wild-paper",
          "note": null,
          "device_type": "edge"
    }
```

### GET /v1/devices/:uuid
Dependent Device Information

**Example**

```bash
curl -X GET $BALENA_SUPERVISOR_ADDRESS/v1/devices/<uuid>?apikey=$BALENA_SUPERVISOR_API_KEY
```

**Response**
`HTTP/1.1 200 OK`

```javascript
{
           "id": 1,
           "uuid": "5ae8cf6e062c033ea57837498ad9b487bfc714e9eab0fed0404ee56e397790",
           "appId": 13015,
           "device_type": "generic-amd64",
           "logs_channel": "69f961abffaad2ff00031b29f718be4fb19e1bfabf1fee7a9ebfb5fa75a1fbdb",
           "deviceId": "47270",
           "is_online": null,
           "name": "blue-sun",
           "status": "Provisioned",
           "download_progress": null,
           "commit": "d43bea5e16658e623088je4b9a91b6606c3c2a0d",
           "targetCommit": "d43bea5e16658e651088ce4b9a21b6606c3c2a0d",
           "env": null,
           "targetEnv": null
       }
```

### PUT /v1/devices/:uuid
Dependent Device Information Update

**Example**

```bash
curl -H "Content-Type: application/json" -X PUT --data /
'{"is_online":true, "status": "Updating", "commit": "339125a7529cb2c2a8c93a0bbd8af69f2d96286ab4f4552cb5cfe99b0d3ee9"}' /
$BALENA_SUPERVISOR_ADDRESS/v1/devices/<uuid>?apikey=$BALENA_SUPERVISOR_API_KEY
```

**Response**
`HTTP/1.1 200 OK`

```javascript
{
           "id": 1,
           "uuid": "5ae8cf6e062c033ea38437498ad9b482bcc714e9eab0fed0404ee56e397790",
           "appId": 13015,
           "device_type": "generic-amd64",
           "logs_channel": "69f961abffaad2ff66031b29f712be4fb19e1bfabf1fee7a9ebfb5fa05a1fbdb",
           "deviceId": "47270",
           "is_online": true,
           "name": "blue-sun",
           "status": "Updating",
           "download_progress": null,
           "commit": "d43bea5e16658e653088ce4b9a11b6606c3c2a0d",
           "targetCommit": "d43bea5e16658e653088se4b9a91b6606c3c2a0d",
           "env": null,
           "targetEnv": null
       }
```

### POST /v1/devices/:uuid/logs
Dependent Device Log

**Example**

```bash
curl -H "Content-Type: application/json" -X POST --data '{"message":"detected movement","timestamp":1472142960}' /
$BALENA_SUPERVISOR_ADDRESS/v1/devices/<uuid>/logs?apikey=$BALENA_SUPERVISOR_API_KEY
```
**Response**
`HTTP/1.1 202 ACCEPTED`

## Hooks (the requests the balena Supervisor performs)

### Hook configuration

You can point the supervisor where to find the hook server via a configuration variable.

- `BALENA_DEPENDENT_DEVICES_HOOK_ADDRESS` _(defaults to `http://0.0.0.0:1337/v1/devices/`)_

It's worth mentioning (as described below) that the supervisor will append the dependent device uuid (`<uuid>` in the hook descriptions) to every hook request URL

### PUT /v1/devices/:uuid/restart
Dependent Device Restart Notification

**Example**

```bash
curl -H "Content-Type: application/json" -X PUT /
http://127.0.0.1:1337/v1/devices/<uuid>/restart
```
**Response**
`HTTP/1.1 200 OK`

### PUT /v1/devices/:uuid
Dependent Device Update Notification

**Example**

```bash
curl -H "Content-Type: application/json" -X PUT /
--data '{"commit":" <commit>","environment": "<environment>"}' http://127.0.0.1:1337/v1/devices/<uuid>
```
**Responses**
* `HTTP/1.1 200 OK` Acknowledgement of the notification without further trials: The Supervisor won't repeat the hook request
* `HTTP/1.1 202 ACCEPTED`Acknowledgement of the notification with validation: the Supervisor will repeat the hook request until the dependent device information gets updated via `Dependent Device Information Update` endpoint

### DELETE /v1/devices/:uuid
Dependent Device Delete Notification

**Example**

```bash
curl -X DELETE http://127.0.0.1:1337/v1/devices/<uuid>
```
**Response**
`HTTP/1.1 200 OK`