Skip to content

3.2. HTTP client

John edited this page Jul 2, 2017 · 15 revisions

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 dynamic 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 for named values
  • full[=true]: include all available attributes
  • required[=true]: retrieve the data from the bus if not yet cached
  • 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, zz, id, fielddefs)
  • 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": {
  "CfgHeatSinkType": {
   "name": "CfgHeatSinkType",
   "lastup": 1483894145,
   "zz": "50",
   "fields": {
    "type": {"value": "mixer"}
   },
   "passive": false,
   "write": false
  },
  "DateTime": {
   "name": "DateTime",
   "lastup": 1483894132,
   "zz": "50",
   "fields": {
    "state": {"value": "valid"},
    "time": {"value": "17:48:54"},
    "date": {"value": "08.01.2017"},
    "temp": {"value": -1.125}
   },
   "passive": false,
   "write": false
  },
 },
 "global": {
  "signal": true,
  "lastup": 1483894147
 }
}

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

Clone this wiki locally