DaTtSs API Documentation

DaTtSs offers REST APIs for aggregation as well as access to aggregated and realtime data. This document presents these APIs and how they should be used to build a driver in a new programming language or a client to access DaTtSs data.

This document focuses on the Aggregation API since the Data API does not yet support anything else than cookie authentication at the moment. Additionally, the Aggregation API is quite specific to DaTtSs as drivers are expected to pre-aggregate data before sending it to our servers.

Aggregation API

The Aggregation API is composed of a unique endpoint PUT /agg which expects a auth parameter (the user AUTH_KEY) as well as a JSON formatted body.

PUT http://dattss.com/agg?auth=_USER_AUTH_KEY_

DaTtSs drivers are supposed to pre-aggregate the data they capture into what we call a partial-aggregate before sending it to DaTtSs (see Coding a Driver for DaTtSs). A partial-aggregate is an aggregated representation of the data the a driver has captured for a given process and a given statistic in the last push-period (by default 5s):

/* PARTIAL := */ { 
  typ: 'ms',         // the statistic type 'c'|'g'|'ms'
  nam: 'view',       // the statistic name
  pct: 0.1,          // the percentage used for percentile calculation
  sum: 123149,       // the sum all received values during the push-period
  cnt: 9874,         // the number of values received during the push-period
  max: 123,          // the maximal value received during the push-period
  min: 4,            // the minimal value received during the push-period 
  lst: 15,           // the last value received during the push-period
  fst: 12,           // the first value received during the push-period
  bot: 11,           // the (pct)-th percentile
  top: 15,           // the (1-pct)-th percentile
  emp: false         // should the stat be visually emphasized
};

These partial-aggregates are grouped by process. A driver is in charge of sending all the partial-aggregates relative to a process after each push-period. The PUT /agg endpoint therefore expect the following body structure:

/* BODY:= */ { 
  nam: 'dattss-srv',      // the process name
  upt: 14578,             // the process uptime in seconds
  prt: {          
    c: [ PARTIAL ],       // a list of 'c'-type partial aggregates
    g: [ PARTIAL ],       // a list of 'g'-type partial aggregates 
    ms: [ PARTIAL ]       // a list of 'ms'-type partial aggregates
  }
};