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 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 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

        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

        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 Provisioning (API Key) role assigned to it for this endpoint to work.

Main features of node_settings:

  • fetch network configuration

    • uplinks (OpenVPN L2, CloudLink/Bondix, 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 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