eGauge WebAPI (4.6)

eGauge Meter API

Download OpenAPI description
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

Activate a service

Request

Activate a service with an external provider (web server).

This request returns a token which can then be used to monitor the status of the operation. See /sys/status/token/result for details.

Bodyapplication/json
servicestringrequired

The type of service to activate. This can be alert for the alert reporting service or push for the data-sharing service.

Enum"alert""push"
providerstringrequired

The name of the service provider with which to activate the service.

Example: "Cloudly's Alert Service"
curl -i -X POST \
  https://webapi.egauge.net/_mock/webapi/4.6/openapi/cmd/activate \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "service": "alert",
    "provider": "Cloudly'\''s Alert Service"
  }'

Responses

Activation response.

Bodyapplication/json
tokenstring>= 32 characters

A status token. This token is a hexadecimal string (typically 32 characters long) which can be used to check on the current status of a potentially long-running operation. The current status can be retrieved from URL /sys/status/token.

Example: "473c31462e62848b5352314dfc608669"
errorstring(ErrorString)

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

Response
application/json
{ "token": "473c31462e62848b5352314dfc608669", "error": "Error message (present if an error occurred)." }

Cancel pending operation

Request

Cancel the long-running operation identified by its token.

Bodyapplication/json
tokenstring>= 32 characters

The token of the operation to be cancelled. This token is the hexadecimal string (typically 32 characters long) that was returned when the operation was initiated.

Example: "473c31462e62848b5352314dfc608669"
curl -i -X POST \
  https://webapi.egauge.net/_mock/webapi/4.6/openapi/cmd/cancel \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "473c31462e62848b5352314dfc608669"
  }'

Responses

Cancel 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)." }

Clear data

Request

Clear data. The string in the request body identifies what data to clear:

  • excess: For register values that are read from a remote device, it is possible that the meter may not be able to reach the remote device at times (e.g., due to a networking problem). If the remote device provides cumulative values, this means that when the remote device becomes accessible again, the cumulative value may have increased significantly, which could then cause a spike in the graphed values for that register. To prevent such spikes, the meter will instead record the jump as an excess and then replay that excess gradually over time so that the meter can catch up to the true value without causing a spike. Executing this command clears to zero the excess of all registers. This will typically cause a spike in the graphed values for any remote registers which had a non-zero excess but, on the positive side, will then ensure that the cumulative values afterwards match those of the remote device(s).

    Note If excess keeps accumulating, it may be better to use the spiky option for remote registers.

  • web_cache: Clears the web server cache of compressed files. Under normal circumstances, it is not necessary to clear this cache explicitly. However, this command can be used in case the cache gets corrupted, e.g., due to a power cycle while the meter is in the middle of writing a cache file.

Bodyapplication/json
string
Enum"excess""web_cache"
curl -i -X POST \
  https://webapi.egauge.net/_mock/webapi/4.6/openapi/cmd/clear \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json'

Responses

Clear 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)." }

Manipulate database

Request

This command supports restoring the database from a backup file, zeroing of all or parts of the database, as well as splitting the positive values of certain registers into separate positive-only registers.

Bodyapplication/json
actionstringrequired

The action to perform. The possible values are:

  • restore: Restores data from a backup file to the device database.
  • zero: Zeroes out one or more registers in the device database.
  • split: Split the positive changes of a net register into a separate positive-only register.
Enum"restore""zero""split"
fromstring(ForeverStamp)

If specified, this limits the operation to data that is not older than the timestamp specified here.

tostring(ForeverStamp)

If specified, this limits the operation to data that is not younger than the timestamp specified here.

regsArray of integers

If specified, the operation is limited to the registers whose database ids appear in this list.

datastring

This member is required for action restore. It contains the binary backup data to be restored, encoded in base64. A device may reject a restore request if this member is larger than 2 MiB. It may therefore be necessary to split up a large backup file into multiple smaller chunks that are then restored one after the other.

more_chunksboolean

This is used only for restore operations. It indicates whether a the backup data has been split up into multiple chunks and the current chunk is to be follow by the next older, adjacent chunk. Setting this flag is not required, but doing so can greatly speed up a restore operation. On the other hand, setting this flag to true without following it up with the next older adjacent chunk can leave the database in a corrupted state, with large spikes at the beginning of the current chunk.

curl -i -X POST \
  https://webapi.egauge.net/_mock/webapi/4.6/openapi/cmd/db \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "restore",
    "from": "1677523091.000900435",
    "to": "1677523091.000900435",
    "regs": [
      0
    ],
    "data": "string",
    "more_chunks": true
  }'

Responses

DB response.

Bodyapplication/json
statusstring

A string describing the successful completion of an operation.

Example: "OK"