onway router public API

Introduction

This document specifies the API for third party applications to interact with onway routers. The API builds upon HTTP/REST and JSON to provide an interface that most developers are familiar with.

Notation

This specification uses the terms controller and handler. A handler is a concrete API URL a third party application interacts with. A controller is a logical group of handlers that are combined under the same URL prefix, but does not otherwise have a meaning in the protocol context.

Requests and response messages herein are specified in JSON Schema, draft version 7. Schema definitions use YAML syntax for easier readability. Examples are provided in JSON format.

API versioning

The router API does not provide any explicit mechanism for API call versioning. If an API changes in incompatible manner, a new controller or handler is added using a new name.

Request or response structures may be extended by new fields in future versions of this specification. Fields newly specified in requests are never mandatory, though.

Note that it is usually not advised to validate responses against the provided schema: Future releases may extend the JSON structure to contain additional fields, but the provided schema validates strictly against the current specification.

Addressing

To interact from a third party application with the herein specified API, that application must use appropriate URLs of the targeted handler. While the suffix of an URL is defined by the handler and its owning controller, the base URL is specific to the deployment.

The router is addressed using local unicast or an anycast IP address. The unicast IP is specific to the local router to address. The anycast address configured on the router answers to requests that any client routes over the local router. The anycast address reserved for local routers is allocated by this specification as 185.12.129.55.

Both unicast and anycast addresses may be resolvable in the DNS. The globally resolvable DNS name for the anycast address 185.12.129.55 is router.onway.ch.

HTTPS is currently not defined in this specification, as the required certificates usually rely on DNS entries. For now, the router API supports requests over plain HTTP, only.

The HTTP server port may be different from TCP port 80, and is deployment specific. The API provides its service directly under the path api under its web service root. So a URL is formed as:

http://<address>:<port>/api/<controller>/<handler>

Usually the API uses the dedicated TCP port 81, hence the URL often is:

http://router.onway.ch:81/api/<controller>/<handler>

Additional parameters may be appended, specific to the handler that specifies their format.

HTTP/REST

When sending a REST request to the API service, the request must use the appropriate HTTP method as documented in each handler.

If the request includes data (in PUT/POST/etc.), the request must include the appropriate content type of that request in a Content-Type HTTP request header.

To get a response, the request must include the expected content type in a Accept HTTP request header. The API service uses this information as a hint to produce the response in the requested format.

For both requests and responses, implementations shall use the application/json content type for all currently defined handlers.

Authentication

Usage of the router API or specific controllers/handlers may be restricted by the router using implementation specific means (source address, router interface, VRF domain, etc.). These access restrictions are not in the scope of this specification, but deployment specific.

Further, authorization may use access tokens in the form of a X-AUTH-TOKEN HTTP request header the third party application includes in each request. Acquiring such tokens is currently not defined in this specification, but usually implemented through additional login handlers.

Response handling

Instead of the response as specified in the handler, the API service may return errors in responses to third party application requests. If a handler returns the response specified in its handler, it uses a 2xx HTTP response code. On error conditions, it returns a HTTP error code, such as:

If the API service replies with a successful status code, it wraps the response in a content attribute along with status data. If the API service replies with a non-successful status code, it includes a more detailed problem description in the problem section. The basic response schema is as follows:

$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
  status:
    description: Status code, always equal to the HTTP response status code
    type: integer
    minimum: 100
    maximum: 999
  reason:
    description: Human-readable interpretation of status code
    type: string
  problem:
    $ref: '#/definitions/problem'
  content:
    $ref: '#/definitions/content'
required:
- status
additionalProperties: False
definitions:

The subschema definition for a problem is:

problem:
  type: object
  properties:
    type:
      description: Problem classification tag
      type: string
    title:
      description: Human-readable interpretation of problem
      type: string
    message:
      description: Additional message string describing problem
      type: string
  required:
  - type
  - title
  additionalProperties: True

Additional properties may be defined for specific problem classification tags, but the specification in the current version does not.

The content subschema is specific to a handler:

content:
  anyOf:
  - $ref: '#/definitions/gnss-location'
  - $ref: '#/definitions/gnss-velocity'
  - $ref: '#/definitions/imu-accel'
  - $ref: '#/definitions/imu-gyro'
  - $ref: '#/definitions/led-status'
  - $ref: '#/definitions/modem-state'
  - $ref: '#/definitions/sms-send'
  - $ref: '#/definitions/system-status'
  - $ref: '#/definitions/time-isodate'
  - $ref: '#/definitions/time-timestamp'
  - $ref: '#/definitions/vpn-tunnel'

Controller

The following controllers group together different REST handlers.

GNSS

The GNSS handler provides GNSS information acquired by one or more of the GNSS modules in a router. The router takes care of selecting the best source or combining them to provide such information. Any GNSS available to the router is considered (GPS, GLONASS, Galileo, etc.).

location

The location handler provides the location information (latitude, longitude, height) of the best GNSS source, along with error estimates. All fields are optional; if no or only a 2D fix is available, or if it is not provided by the GNSS receiver, any of the field may be omitted.

gnss-location:
  type: object
  properties:
    latitude:
      description: Latitude north-south position as angle, in degrees
      type: number
    longitude:
      description: Longitude east/west position as angle, in degrees
      type: number
    altitude:
      description: Altitude above sea-level, in meters
      type: number
    latitude-error:
      description: Latitude error estimate, in meters
      type: number
    longitude-error:
      description: Longitude error estimate, in meters
      type: number
    altitude-error:
      description: Estimated vertical error, in meters
      type: number
  additionalProperties: False
{
  "status": 200,
  "reason": "OK",
  "content": {
    "latitude": 47.3728474,
    "longitude": 8.5303599,
    "altitude": 402,
    "latitude-error": 10,
    "longitude-error": 10
  }
}

velocity

The velocity handler provides the speed and direction information of the best GNSS source, along with error estimates. All fields are optional; if no or only a 2D fix is available, or if it is not provided by the GNSS receiver, any of the field may be omitted.

gnss-velocity:
  type: object
  properties:
    track:
      description: Course over ground, degrees from true north
      type: number
    speed:
      description: Speed over ground, m/s
      type: number
    climb:
      description: Climb (positive) or sink (negative) rate, m/s
      type: number
    track-error:
      description: Direction error estimate in degrees
      type: number
    speed-error:
      description: Speed error estimate in m/s
      type: number
    climb-error:
      description: Climb/sink error estimate in m/s
      type: number
  additionalProperties: False
{
  "status": 200,
  "reason": "OK",
  "content": {
    "track": 12.45,
    "speed": 8.2,
    "climb": -0.2,
    "speed-error": 2
  }
}

IMU

The IMU handler provides direct access to an integrated inertial measurement unit. It exposes accelerometer and gyroscope data measurements.

Each GET returns the currently measured IMU data. A future API release may provide a mechanism to stream real-time data to clients, but for now only a REST API is available, requiring polling.

Sensor data is provided relative to the router orientation using the following axis definition:

         ^  z-axis
         |
         |
         +---------+
        /   Top   /|
       +---------+ |
       |         | +----->  y-axis
       |  Front  |/
       +---------+
      /
     /
    v  x-axis

On vehicles, the orientation is adjusted to provide values relative to the vehicle.

accel

The accel handler provides accelerometer data currently measured.

imu-accel:
  type: object
  properties:
    x:
      description: current x-axis force, m/s²
      type: number
    y:
      description: current y-axis force, m/s²
      type: number
    z:
      description: current z-axis force, m/s²
      type: number
  additionalProperties: False
{
  "status": 200,
  "reason": "OK",
  "content": {
    "x": -1.23,
    "y": 0,
    "z": 9.81
  }
}

gyro

The gyro handler provides gyroscope data currently measured.

imu-gyro:
  type: object
  properties:
    x:
      description: current x-axis angular rate, degree/s
      type: number
    y:
      description: current y-axis angular rate, degree/s
      type: number
    z:
      description: current z-axis angular rate, degree/s
      type: number
  additionalProperties: False
{
  "status": 200,
  "reason": "OK",
  "content": {
    "x": 0.2,
    "y": 0,
    "z": -3.2
  }
}

LED

The LED API controller provides information about the LED lights of the router.

status

The status handler returns the current state and color of all router status LEDs. All known LEDs are returned and are mandatory. LEDs that are not physically present on the router hardware are returned anyway. All LEDs contain the mandatory state property which either contains the current LED light color or that it’s turned off.

led-status:
  type: object
  required:
  - system
  - mobile1
  - mobile2
  - vpn
  - wlan1
  - wlan2
  - gnss
  - misc
  maxProperties: 8
  additionalProperties:
    type: object
    required:
    - state
    maxProperties: 1
    properties:
      state:
        type: string
        enum:
        - 'off'
        - red
        - orange
        - green
{
  "status": 200,
  "reason": "OK",
  "content": {
    "system": {
      "state": "green"
    },
    "mobile1": {
      "state": "off"
    },
    "mobile2": {
      "state": "off"
    },
    "vpn": {
      "state": "green"
    },
    "wlan1": {
      "state": "green"
    },
    "wlan2": {
      "state": "green"
    },
    "gnss": {
      "state": "off"
    },
    "misc": {
      "state": "off"
    }
  }
}

MODEM

The MODEM handler provides modem state information of the router.

state

The state handler provides modem state information of all the modems found on the router. The state returns the connection state of the modem and the most important figures of the modem signal.

The connection state can be of the following:

For further information about the meaning of the modem signal figures refer to the related documentation.

modem-state:
  type: object
  patternProperties:
    ^(mbm)[0-9]$:
      type: object
      properties:
        state:
          description: Modem connection state
          type: string
          enum:
          - ue
          - sim
          - net
          - pdp
          - ip
        gsm:
          description: 2G/GSM signal information
          type: object
          properties:
            rssi:
              description: GSM Received Signal Strength Indicator, dBm
              type: number
          additionalProperties: False
        umts:
          description: 3G/UMTS signal information
          type: object
          properties:
            rssi:
              description: UMTS Received Signal Strength Indicator, dBm
              type: number
            ecio:
              description: EC/IO signal quality indicator, dB
              type: number
          additionalProperties: False
        lte:
          description: 4G/LTE signal information
          type: object
          properties:
            rssi:
              description: LTE Received Signal Strength Indicator, dBm
              type: number
            rsrp:
              description: Reference Signal Received Power, dBm
              type: number
            rsrq:
              description: Reference Signal Received Quality, dB
              type: number
            sinr:
              description: Signal to Interference plus Noise Ratio, dB
              type: number
          additionalProperties: False
        5g:
          description: 5G signal information
          type: object
          properties:
            rsrp:
              description: Reference Signal Received Power, dBm
              type: number
            rsrq:
              description: Reference Signal Received Quality, dB
              type: number
          additionalProperties: False
      required:
      - state
      additionalProperties: False
  additionalProperties": False

Signal information for multiple radio access technologies can be included in the same response, for example for 5G Non-Standalone connections.

{
  "status": 200,
  "reason": "OK",
  "content": {
    "mbm0": {
      "state": "net",
      "lte": {
        "rssi": -94,
        "rsrp": -119,
        "rsrq": -19,
        "sinr": -4
      }
    },
    "mbm1": {
      "state": "ip",
      "gsm": {
        "rssi": -94
      }
    },
    "mbm2": {
      "state": "pdp",
      "umts": {
        "rssi": -60,
        "ecio": -4
      }
    }
  }
}

SMS

The SMS handler provides a text message gateway to interface with other users of the telephone system.

send

The send handler sends an SMS text message to a recipient with the text and phone number defined in the JSON request. If the modem property is given, the SMS is sent over the specific modem interface name; if omitted, an arbitrary modem with network connectivity is selected. If the message is too long, the API will return an HTTP 413 (Payload Too Large) error. If the message could not be delivered, the API will return an HTTP 503 (Service Unavailable) error.

request-schema:

sms-send:
  type: object
  required:
  - recipient
  - message
  additionalProperties: False
  properties:
    modem:
      type: string
      description: Interface name of modem to send SMS from
    recipient:
      type: string
      description: Recipient phone number in E.164 format (+...)
    message:
      type: string
      description: Text content to send in message, up to 70 characters

Example request (http://localhost:80/api/sms/send):

{
  "modem": "mbm0",
  "recipient": "+41781234567",
  "message": "Your access code is 1234"
}

Example response:

{
  "status": 200,
  "reason": "OK"
}

SYSTEM

The SYSTEM handler provides information about the system, software and hardware aspects of the router.

status

The status handler returns the current system status information and identification details of the router.

This includes the unique device identifier, hardware revision, software version and if the router is currently running in fallback state.

system-status:
  type: object
  required:
  - id
  - hardware-revision
  - software-version
  - fallback
  additionalProperties: False
  properties:
    id:
      type: string
      description: Unique device identifier: 'Manufacturer/Model/Serial'
    hardware-revision:
      type: string
      description: Device hardware revision
    software-version:
      type: string
      description: Current software version
    fallback:
      type: boolean
      description: True if device is running in fallback state
{
  "status": 200,
  "reason": "OK",
  "content": {
    "software-version": "2.12.0",
    "id": "NetModule/3800/00112BFFDD89",
    "hardware-revision": "1.2",
    "fallback": false
  }
}

TIME

The TIME handler provides time information of the router.

iso-date

The iso-date handler provides the same information as the timestamp handler. The only difference is the formatting of the fields. The values are formatted in ISO-8601 format with zero UTC offset.

If the system time is not yet synchronized the fields are omitted.

time-iso-date:
  type: object
  properties:
    time:
      description: System time, gradually adjusted, IS0-8601 formatted, zero UTC offset
      type: number
    raw:
      description: System time, more accurate but affected by discontinuous jumps, IS0-8601 formatted, zero UTC offset
      type: number
  additionalProperties: False
{
  "status": 200,
  "reason": "OK",
  "content": {
    "time": "2020-12-07T15:52:28.245Z",
    "raw": "2020-12-07T15:52:28.245Z"
  }
}

timestamp

The timestamp handler provides the time information of the router. There are two fields available, a system time in microseconds which is gradually adjusted and less accurate. The second field is a more accurate raw time but it is affected by discontinuous jumps.

If the system time is not yet synchronized the fields are omitted.

time-timestamp:
  type: object
  properties:
    time:
      description: System time, gradually adjusted, microseconds since Unix Epoch
      type: number
    raw:
      description: Raw system time, more accurate but affected by discontinuous jumps, microseconds since Unix Epoch
      type: number
  additionalProperties: False
{
  "status": 200,
  "reason": "OK",
  "content": {
    "time": 1607356348245765,
    "raw": 1607356348245765
  }
}

VPN

The VPN handler provides VPN tunnel state information.

tunnel

The tunnel handler provides VPN tunnel state information. It includes the uplinks currently active for tunnels and includes quality/latency estimates for each uplink. This allows clients to check connectivity to backend systems and what quality to expect or what traffic may cost.

vpn-tunnel:
  type: object
  patternProperties:
    ^.*$:
      description: Name of tunnel configuration
      type: object
      properties:
        uplinks:
          type: object
          patternProperties:
            ^.*$:
              Description: Uplink interface name active for tunnel
              type: object
              properties:
                quality:
                  Description: Uplink quality value, higher is better
                  type: number
                  minimum: 0
                latency:
                  Description: Current uplink latency, in ms
                  type: number
                  minimum: 0
                load:
                  Description: Share of load uplink takes for tunnel, in %
                  type: number
                  minimum: 0
                  maximum: 100
              required:
              - quality
              - load
              additionalProperties: False
          additionalProperties: False
      additionalProperties: False
  additionalProperties: False

onway routers can establish multiple tunnels identified by a name, and each tunnel may use multiple uplinks as underlay. The load sharing mechanism constantly monitors the tunnels, their latency and quality, and then calculates load sharing weights across all usable uplinks. If a tunnel configuration uses uplink priorities, some uplinks may not be used if a cheaper uplink is available. This API reports uplinks currently actively participating in the tunnel, only, and omits those currently in hot-standby mode.

{
  "status": 200,
  "reason": "OK",
  "content": {
    "guest-wifi": {
      "uplinks": {
        "mbm0": {
          "quality": 167,
          "latency": 65,
          "load": 21
        },
        "wfi0": {
          "quality": 200,
          "latency": 12,
          "load": 79
        }
      }
    }
  }
}

In the above example, the VPN tunnel named guest-wifi is established redundantly over the broadband modem mbm0 and the WiFi uplink wfi0. The wfi0 uplink has a lower latency and a higher estimated uplink quality, hence has to handle a higher share of the traffic to tunnel.