eGauge WebAPI (4.6)

eGauge Meter API

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License Common Documentation License 1.0
Languages
Servers
Mock server
https://webapi.egauge.net/_mock/webapi/4.6/openapi/
The WebAPI server
https://{devname}.egauge.io/api/

Introduction

The eGauge WebAPI is a JSON-based API that provides access to eGauge meters. It offers secure means to read device data, configure the device, and perform various control operations.

The WebAPI is intended to eventually replace the eGauge XML API. For new applications, developers are encouraged to use WebAPI rather than the legacy XML API.

/auth

The authentication service. Clients can use this to obtain and manage tokens that grant access to the other resources in this API.

The meter uses JSON Web Tokens (JWT or simply token) to restrict access to protected resources. Clients must include such tokens in requests via the HTTP Authorization header. This header must have the form:

Authorization: Bearer JWT

where JWT is a valid token.

Tokens are valid for a limited time; typically for about 10 minutes. However, a meter may revoke a token earlier, e.g., due to a reboot.

Operations

/capture

The capture service allows collecting waveform data for configured input channels.

Operations

/cmd

The service provides the ability to execute various operations for their side effects, such as rebooting the meter. Unless stated otherwise, the resources in this service are available only to users with the save right (see /auth/rights).

Operations

/config

The meter configuration service.

The endpoints under /config provide common method semantics and atomicity guarantees as described below.

Operations

/config/alert

The alert configuration of the meter.

Operations

Get /config/alert

Request

Query
max-depthinteger>= 1

Limit output depth of the response. See Max-Depth.

Example: max-depth=2
filterstring
Example: filter={foo,bar}
curl -i -X GET \
  'https://webapi.egauge.net/_mock/webapi/4.6/openapi/config/alert?filter=string&max-depth=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Normal response.

Headers
ETagstring

The returned value is a tag that uniquely identifies the meter configuration. Subsequent modification requests can include this tag in an If-Match header to apply the modification only if the configuration has changed since the tag was obtained.

Bodyapplication/json
resultobject(configAlert)

The alert configuration of the meter.

errorstring(ErrorString)

A message describing the first error that occurred. This member is present only if an error occurred.

Response
application/json
{
  "result": {
    "custom": [ … ],
    "reporter": { … },
    "sys-prio": [ … ]
  },
  "error": "Error message (present if an error occurred)."
}

Replace /config/alert

Request

Bodyapplication/json
customArray of objects(configAlertCustom)

Up to 32 custom alerts.

Custom alerts consist of an arbitrary boolean condition that is checked at certain times. When the condition evaluates to true, the alert is triggered.

reporterobject(configAlertReporter)

The alert reporting configuration. Alerts may be reported via a web server or via an email server.

sys-prioArray of integers(configAlertSysPrio)

The priority of each system-generated alert. /sys/alert provides a description of these alerts.

curl -i -X PUT \
  https://webapi.egauge.net/_mock/webapi/4.6/openapi/config/alert \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom": [
      {
        "name": "temperature alert",
        "detail": "It is hot in here: %l C!",
        "frequency": "sec",
        "priority": 7,
        "cond": {
          "lhs": "temp_internal()",
          "op": "<",
          "rhs": "30"
        }
      }
    ],
    "reporter": {
      "web": {
        "min-priority": 7,
        "service": "",
        "uri": "https://alerts.com/report",
        "options": "gzip,secure",
        "user": "jsmith",
        "password": "secret!"
      },
      "mail": {
        "server": "smtp.mail.com",
        "user": "egaugealert@mail.com",
        "password": "string",
        "from-address": "eGauge1345",
        "to": [
          {
            "format": "string",
            "min-priority": 3,
            "address": "user@site.com"
          }
        ]
      }
    },
    "sys-prio": [
      0,
      0,
      7,
      0,
      7,
      4,
      0,
      0,
      1,
      6,
      0,
      0,
      0,
      5,
      0,
      0,
      0,
      0,
      0,
      0
    ]
  }'

Responses

Normal response.

Bodyapplication/json
statusstring

A string describing the successful completion of an operation.

Example: "OK"
errorstring(ErrorString)

A message describing the first error that occurred. This member is present only if an error occurred.

Response
application/json
{
  "status": "OK",
  "error": "Error message (present if an error occurred)."
}

Update /config/alert

Request

Bodyapplication/json
customArray of objects(configAlertCustom)

Up to 32 custom alerts.

Custom alerts consist of an arbitrary boolean condition that is checked at certain times. When the condition evaluates to true, the alert is triggered.

reporterobject(configAlertReporter)

The alert reporting configuration. Alerts may be reported via a web server or via an email server.

sys-prioArray of integers(configAlertSysPrio)

The priority of each system-generated alert. /sys/alert provides a description of these alerts.

curl -i -X POST \
  https://webapi.egauge.net/_mock/webapi/4.6/openapi/config/alert \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom": [
      {
        "name": "temperature alert",
        "detail": "It is hot in here: %l C!",
        "frequency": "sec",
        "priority": 7,
        "cond": {
          "lhs": "temp_internal()",
          "op": "<",
          "rhs": "30"
        }
      }
    ],
    "reporter": {
      "web": {
        "min-priority": 7,
        "service": "",
        "uri": "https://alerts.com/report",
        "options": "gzip,secure",
        "user": "jsmith",
        "password": "secret!"
      },
      "mail": {
        "server": "smtp.mail.com",
        "user": "egaugealert@mail.com",
        "password": "string",
        "from-address": "eGauge1345",
        "to": [
          {
            "format": "string",
            "min-priority": 3,
            "address": "user@site.com"
          }
        ]
      }
    },
    "sys-prio": [
      0,
      0,
      7,
      0,
      7,
      4,
      0,
      0,
      1,
      6,
      0,
      0,
      0,
      5,
      0,
      0,
      0,
      0,
      0,
      0
    ]
  }'

Responses

Normal response.

Bodyapplication/json
statusstring

A string describing the successful completion of an operation.

Example: "OK"
errorstring(ErrorString)

A message describing the first error that occurred. This member is present only if an error occurred.

Response
application/json
{
  "status": "OK",
  "error": "Error message (present if an error occurred)."
}

Delete /config/alert

Request

Reset to default. See the descriptions of the individual endpoints for their default values. Commonly, arrays and strings are cleared to empty, numbers are cleared to 0, and booleans are cleared to false.

curl -i -X DELETE \
  https://webapi.egauge.net/_mock/webapi/4.6/openapi/config/alert \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'