# APIs for 3rd party devices

Unwired Edge Cloud provides configuration and orchestration for two kinds of devices:
- devices running Unwired Edge Cloud OS
- devices running 3rd party operating systems

For devices running Unwired Edge Cloud OS all features are available and generally only
limited by hardware feature set (e.g. CloudLink uplink aggregation is only available for
devices with multiple uplinks).

Depending on the feature set of the 3rd party operating system, the following Unwired Edge
Cloud features are available to arbitrary 3rd party devices. In brackets the OS requirements
are specified:
- basic API updates (requires cronjob/shell scripts with jq/any or simple programming
  language with basic JSON support), this includes:
  - regular configuration updates from the API
  - automatic certificate rotation
  - automatic heartbeat to show online/offline status in the UI
- public WiFi online portal (requires OpenVPN L2 client), this includes:
  - full CMS for captive portals including all Unwired Edge WiFi features
  - bandwidth and traffic policies for WiFi users
  - easy editing for non-technical users in the CMS
  - automated content imports from 3rd party sources (video, audio,...)
- CloudLink aggregated multiple uplinks (requires a Bondix S.A.NE client for the platform)

If you need a fully featured public wifi online portal or CloudLink for uplink aggregation
across multiple ethernet/DSL/satellite/modem uplinks, using the APIs described on this page
will make it possible to integrate with these services.

If you need help with integration please contact [sales@unwirednetworks.com](mailto:sales@unwirednetworks.com)
for technical consulting.

## flow charts

Participants:
- appliance: a data center endpoint in a specific geo and region offering the service
- router: a locally or cloud-configured router that connects to an appliance
- user: a user configuring a router either directly or through a cloud service
- cloud-service: a cloud service that configures a router on behalf of a user

### directly calling the API from the router

Overview:
- the router calls MTSG_get_appliances to fetch a list of geo + region
  values where the service is available
- the user selects which geo + region to connect to
  - and provides optional client license key if required
- the router then calls node_settings to retrieve the connection configuration
- the router uses that connection configuration to connect to the appliance
- the router regularly calls node_settings to refresh the connection configuration
  in order to react to server changes or certificate rotations

```{mermaid}
sequenceDiagram
  participant user
  participant router
  participant API
  participant appliance
  router->>API: query<br/>MTSG_get_appliances
  API->>router: result:<br/>list of geos and regions
  user->>router: select geo + region in UI
  router->>API: query<br/>node_settings with<br/>geo + region + create device on-demand
  API->>API: create device,<br/>add configuration and set geo + region
  API->>router: result:<br/>connection configuration
  router->>appliance: connect using<br/>connection configuration
  router->>API: regularly update connection<br/>configuration using node_settings
  API->>router: updated connection configuration<br/>(e.g. server changes or certificate rotations)
```

### calling the API from a central cloud service

Overview:
- the cloud-service calls MTSG_get_appliances to fetch a list of geo + region
  values where the service is available
- the user selects which geo + region to connect to
  - and provides optional client license key if required
- the cloud-service then calls node_settings to retrieve the connection configuration
- the cloud-service then transfers this connection configuration to the router
- the router uses that connection configuration to connect to the appliance
- the cloud-service regularly calls node_settings to refresh the connection configuration
  in order to react to server changes or certificate rotations

```{mermaid}
sequenceDiagram
  participant user
  participant cloud-service
  participant API
  participant router
  participant appliance
  cloud-service->>API: query<br/>MTSG_get_appliances
  API->>cloud-service: result:<br/>list of geos and regions
  user->>cloud-service: select geo + region in UI
  cloud-service->>API: query<br/>node_settings with<br/>geo + region + create device on-demand
  API->>API: create device,<br/>add configuration and set geo + region
  API->>cloud-service: result:<br/>connection configuration
  cloud-service->>router: send connection configuration
  router->>appliance: connect using<br/>connection configuration
  cloud-service->>API: regularly update connection<br/>configuration using node_settings
  API->>cloud-service: updated connection configuration<br/>(e.g. server changes or certificate rotations)
```

## node_settings - main configuration API

The main configuration API is called ```node_settings```. There is a reference implementation
for documentation purposes available on request.

How to use the API:
- input: API key (authz) + device MAC
- output: JSON with the full configuration

```{caution}
API key must have "3rd Party Device Priovisioning" role assigned to it for this endpoint to work.
```

Main features of node_settings:
- fetch network configuration
  - uplinks (OpenVPN L2, CloudLink/Bondix S.A.NE, public WiFi)
  - client networks (LAN ethernet and WiFi network configurations, including open/WPA2-PSK wifi
    configuration and ethernet VLANs)
- for each network configuration
  - full certificate based key material that is automatically rotated
    - the ```minimum_ttl``` parameter of ```node_settings``` allows you to specify a custom minimum
      TTL for the key material, which is useful for manual configurations or custom szenarios
      - ```minimum_ttl``` is overriden by your maximum valid license period.
  - no hardcoded or rarely-changed passwords required
- a ```changed``` parameter in the response that signals the last configuration change
  - on configuration change a running configuration will need to be reloaded appropriately
  - typically this means that either connection parameters (e.g. server hostname) changed or
    a certificate rotation happened

Additional/advanced features of node_settings:
- ```upsert_device_on_demand``` will create or update device on demand:
  - a device can be created automatically on first call
  - a default network configuration will be created or updated with the requested network feature parameter
- client-controlled geo/region settings
  - the client can request a geo/region setting (the input values can be queried using ```MTSG_get_appliances```)
- license_code
  - this is a required field for individually licensed products
  - the client device can use this field to pass a per-client license to be bound to the device

The API is available as GraphQL API similar to all other APIs of Unwired Edge Cloud.

### License Code Usage

The ```license_code``` in node_settings is optional, but required if all of the following conditions are true:
- Customer's billing type is not ```disabled```. 
  - You can check your current billing type in Access Managment / Customer.
- There's no ```license_code``` associated with the device already.
  - Or the period of the associated license has been expired.
    - You can use ```DM_get_bound_node_licenses``` to check what active licenses a node has, without calling node_settings first.
  - Or the assigned/associated licenses are not valid for the requested access type. 
    - For example cloudlink product license will not be valid for a public wifi config.

If the billing type of the customer you are using has been changed to ```invoice```. 
New license codes can be created using the ```DM_create_licenses``` mutation.
Existing license codes can be queried for using the ```DM_get_licenses``` query.

## MTSG_get_appliances - get available service geo regions

This API allows you to query the available service geo regions for a requested service that
requires a data center endpoint. This is the case for:

- CloudLink when connecting to global Unwired Edge Cloud infrastructure
- public WiFi when connecting to global Unwired Edge Cloud infrastructure

Unwired Networks operates many services in different geo regions across the world as a
managed software as a service (SaaS) offering.

## Example implementation CloudLink

Geo/region selection
- use ```MTSG_get_appliances``` to query available geo and region values for the feature ```cloudlink```
- let the user choose from available options

Typical implementation for ```node_settings```:
- call node_settings approximately every 10 minutes
- check the ```changed``` parameter in the response to see if something changed
  - if yes -> need to reload configuration with new values (e.g. new server hostname
    or changed certificates/key material)
- in the response will be a full CloudLink/Bondix S.A.NE configuration
  - use this configuration to connect to the server or server infrastructure
  - this will work both with custom servers and the fully managed CloudLink service
    provided through Unwired Edge Cloud
- as soon as the connection to the CloudLink service is established, the client will
  show online in the Unwired Edge Cloud Console

## Example implementation Public WiFi

Geo/region selection
- use ```MTSG_get_appliances``` to query available geo and region values for the feature
  ```public_wifi``` or ```public_wifi_filtered```
  - ```public_wifi_filtered``` adds an additional DNS-based content filter to the service
- let the user choose from available options

Typical implementation for ```node_settings```:
- call node_settings approximately every 10 minutes
- check the ```changed``` parameter in the response to see if something changed
  - if yes -> need to reload configuration with new values (e.g. new server hostname
    or changed certificates/key material)
- in the response will be a full OpenVPN L2 configuration
  - use this configuration to connect the Unwired Edge Cloud server infrastructure
- as soon as the connection to the public WiFi service is established, the client will
  show online in the Unwired Edge Cloud Console
- on the device network configuration
  - bridge the OpenVPN L2 network to your WiFi radio interfaces or LAN ethernet/VLAN
    interfaces
  - this will automatically make all Unwired Edge WiFi features available within the L2
    domain of that wireless or wired LAN network
- you can even configure the client network configuration through Unwired Edge Cloud
  by reading wifi and LAN/VLAN parameters from the ```node_settings``` response
  - this way the full network configuration can be controlled through Unwired Edge Cloud