Version 1.3
This document specifies the API for third party applications to interact with onway mobile routers. The API builds upon HTTP/REST and JSON to provide an interface that most developers are familiar with.
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.
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.
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 api.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:
Usually the API uses the dedicated TCP port 81, hence the URL often is:
Additional parameters may be appended, specific to the handler that specifies their format.
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.
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.
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: TrueAdditional 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:
anyOff:
- $ref: '#/definitions/gnss-location'
- $ref: '#/definitions/gnss-velocity'
- $ref: '#/definitions/imu-accel'
- $ref: '#/definitions/imu-gyro'
- $ref: '#/definitions/led-status'
- $ref: '#/definitions/time-timestamp'
- $ref: '#/definitions/time-isodate'
- $ref: '#/definitions/modem-state'The following controllers group together different REST handlers.
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.).
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.
api/gnss/locationGETapplication/json 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
}
}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.
api/gnss/velocityGETapplication/json 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
}
}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-axisOn vehicles, the orientation is adjusted to provide values relative to the vehicle.
The accel handler provides accelerometer data currently measured.
api/imu/accelGETapplication/json 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: FalseThe gyro handler provides gyroscope data currently measured.
api/imu/gyroGETapplication/json 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: FalseThe LED API controller provides information about the LED lights of the router.
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.
api/led/statusGETapplication/json 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"
}
}
}The TIME handler provides time information of the router.
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.
api/time/timestampGETapplication/json 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: FalseThe 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.
api/time/iso-dateGETapplication/json 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"
}
}The MODEM handler provides modem state information of the router.
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.
api/modem/stateGETapplication/json 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": falseSignal information for multiple radio access technologies can be included in the same response, for example for 5G Non-Standalone connections.