Agile Data API

[craigmulligan]

Agile-data-api Spec

This Spec details the requirements and interface for the agile-data-api. It's responsible for allowing the user to configure the persistence of data that the agile-api captures as well as an API to query the stored data.

It's intentionally simple, basing the requirements off the agile-data-ui spec.

Requirements:

• Ability to set up a service worker(Subscription) for each device + component that runs at user defined interval, queries the agile-api and writes that data to the database.

• Ability to query the database by device, by component and/or by time and return records object.

• Ability to stream records made by a query and watch for any new records made.

• Ability to configure retention policy for database.

Models

We have two models. Subscriptions and Records.

Subscriptions

Subscriptions is a reference to the device + component. A Subscription is a job that is run periodically to write new values to the database.

A Basic representation would look like this:

Subscription
{
  device: 'bleA0E6F8B62304',
  component: 'temperature',
  interval: '86400',
  created_at: '1477491668082'
}

Subscriptions have no relation to Records.

Records

Records store the data returned from the agile-api.

A basic representation:

{
  'deviceID': 'bleA0E6F8B62304',
  'componentID':'Temperature',
  'value':'23.46875',
  'unit':'Degree celsius',
  'format':',
  'lastUpdate':'1477491668082'
}

API

Create subscription for device component

method: POST
url: /api/subscription/:device/:component
body: {
  interval: '86400'
}

Delete subscription for device component

method: DELETE
url: /api/subscription/:device/:component

Update subscription for device component

method: PUT
url: /api/subscription/:device/:component
body: {
  interval: '10000'
}

Read subscription for device component

method: GET
url: /api/subscription/:device/:component

Read subscriptions all subscriptions on gateway

method: GET
url: /api/subscription

Read, Update & Delete subscriptions also accept also accepts the use custom queries.

method: GET
url: /api/subscriptions?query='{"where":{"deviceID":"bleA0E6F8B62304"},"limit":"2","sort":"createdAt DESC"}'

Get all records

If the request is made with with ws then a connect is opened an results will be streamed, if the request is standard http then JSON object will be returned.

method: GET
url: /api/records

Get all records with query

method: GET
url: /api/record?query='{"where":{"deviceID":"bleA0E6F8B62304", "componentID": "temperature"},"limit":"500","sort":"lastUpdate DESC"}'

Delete all records matching query

method: DELETE
url: /api/record?query='{"where":{"deviceID":"bleA0E6F8B62304", "componentID": "temperature"},"limit":"500","sort":"lastUpdate DESC"}'

Create new record

method: POST
url: /api/record
body: {
  'deviceID': 'bleA0E6F8B62304',
  'componentID':'Temperature',
  'value':'23.46875',
  'unit':'Degree celsius',
  'format':',
  'lastUpdate':'1477491668082'
}

Update Retention

Point at which old records are deleted.

Note It maybe possible to make this more granular eg. for add an expiration for each Record. But the difficulty depends on implementation details.

method: PUT
url: /api/retention
body: {
  expiration: '3d'
}

Create Retention

Point at which old records are deleted.

method: POST
url: /api/retention
body: {
  expiration: '3d'
}

SDK

We'll also add new data methods to the sdk. For instance you could query the data API like so.

agile.data.records({
  where: {
    deviceId: 'bleA0E6F8B62304'
  }
  limit: 500
}).then((records) => {
  console.log(records);
});

Let me know if I've missed any functionality that we need for agile-data-ui or any simplifications that could be made.