3.2. HTTP client

Introduction

The HTTP port (see --httpport) of ebusd serves static files from the configured directory (see --httppath) as well as dynamic data from the message definitions.

The base URL for the data part is "/data" and may be extended by the following path segments for filtering the corresponding data:

• circuit name
• message name

The data URL path understood thus "/data[/[circuit][/[name]]]" where parts in brackets are optional.

In addition to these path components, the following query parameters are accepted:

• since=seconds: limit to messages that have changed since the specified UTC seconds
• poll=prio: set the poll priority of matching message(s) to prio
• exact[=true]: exact search for circuit/message name
• verbose[=true]: include comments and field units
• indexed[=true]: return field indexes instead of names
• numeric[=true]: return numeric values of value list entries
• valuename[=true]: include value and name of value list entries
• full[=true]: include all available attributes
• required[=true]: retrieve the data from the bus if not yet cached
• maxage[=seconds]: retrieve the data from the bus if cached value is older than specified seconds (or not present at all)
• write[=true]: include write messages in addition to read
• raw[=true]: include the raw master/slave symbols as int arrays
• def[=true]: include message/field definition (qq, id, fielddefs)
• define=DEFINITION: (re-)define the message from DEFINITION (in CSV format)
• user=USER: authenticate with USER name
• secret=SECRET: authenticate with user SECRET

Here is an example verbose query for all messages in the mixer circuit "mc" that were changed since Sunday, January 8th 2017, 4:40 PM (CET) when the HTTP port was set to 8080:
http://localhost:8080/data/mc?verbose&since=1483890000&exact

The response to such a URL is a JSON object with a "global" property as well as an own property for each circuit matching the request path. Each property is again a JSON object with key-value pairs and for each circuit it contains the list of named messages.

The "global" property is included in every response and contains the following keys (besides others):

• "signal": true or false depending on the eBUS signal state
• "lastup": the time in UTC seconds of the last received update for all matched messages

Here is an excerpt of an answer to the query above:

{
 "mc": {
  "messages": {
   "CfgHeatSinkType": {
    "name": "CfgHeatSinkType",
    "passive": false,
    "write": false,
    "lastup": 1498281188,
    "zz": 80,
    "fields": {
     "type": {"value": "mixer"}
    }
   },
   "DateTime": {
    "name": "DateTime",
    "passive": false,
    "write": false,
    "lastup": 1498981415,
    "zz": 80,
    "fields": {
     "state": {"value": "valid"},
     "time": {"value": "09:43:37"},
     "date": {"value": "02.07.2017"},
     "temp": {"value": 14.750}
    }
   }
  }
 },
 "global": {
  "version": "3.0pre.9420946",
  "updatecheck": "OK, 1 newer configuration files available",
  "signal": true,
  "symbolrate": 22,
  "maxsymbolrate": 191,
  "qq": 49,
  "reconnects": 2,
  "masters": 5,
  "messages": 893,
  "lastup": 1498981441
 }
}

A comprehensive description of this API is available on SwaggerHub and in the repository.