starfish-sdk v0.9.4

Starfish JS

A Javascript Wrapper for the Starfish APIs

Install

npm install starfish-sdk

Usage

  const Starfish = require('starfish-sdk');
  const options = {
    'credentials' : {
      'clientId' : 'your-client-id',
      'clientSecret' : 'your-secret'
    }
  }
  var starfish = new Starfish(options)

Authentication

There are two ways to authenticate with the Starfish Data Platform

1. Credentials: Use the credentials in secure backend environments only as they are not meant to be exposed. You can retrieve your clientId and secret when signing up for the Starfish Data Platform developer program.
2. Token: You can get a token directly from the Tokens API using valid credentials. This token is suitable for use in a browser as it is short lived.

Specify either a credentials object or a token in the Starfish constructor (not both). If using a credentials object, the token refreshing is handled for you automatically.

Examples

The following examples assume that you have an instance of starfish named starfish. See Usage.

Post Observation For A Known Device

  const deviceId = "12345678-1234-1234-1234-0123456789ab"
  const observation = {
    observations: [
      {
        timestamp: new Date().toISOString(),
        temperature: 35,
        accelerometer: {
  	x: 0.01,
  	y: 0.5,
  	z: 1.6
        }
      }
    ]
  }

  starfish.postDeviceObservation(deviceId, observation, (err, data) => {
    if(err) {
      console.log("Error:", err)
    } else {
      console.log("Success")
    }
  })

List Devices

  starfish.getDevices((err, data) => {
    if(err) {
      console.log("Error:", err)
    } else {
      console.log("Return devices: ", data)
    }
  })

Query Devices by deviceType

  starfish.queryDevices({deviceType:'type'}, (err, data) => {
    if(err) {
      console.log("Error:", err)
    } else {
      console.log("Return devices: ", data)
    }
  })

Get Device Observations

This will return the latest observations for specified device (upto 1MB of observations).

Use getNextPage to paginate through the observations.

 const deviceId = "12345678-1234-1234-1234-0123456789ab"

 starfish.getDeviceObservations(deviceId, (err, data) => {
    if(err) {
      console.log("Error:", err)
    } else {
      console.log("Return device observations: ", JSON.stringify(data))
      if(response.next_page)
        starfish.getNextPage(response.next_page, .......)
    }
  })

Get All Device Observations

This will return the latest observations for all devices

starfish.getObservations((err, response) => {
  if(err) {
    console.log("Error:", err)
  } else {
    console.log("Return all device observations: ", JSON.stringify(response.data))
  }
})

Query Observations

This will return all observations that matched the filter criteria (upto 1MB of observations)

Use getNextPage to paginate through the observations.

Observations can be queried using:

const query = {limit: 10}

starfish.queryObservations(query, (err, response) => {
   if(err) {
     console.log("Error:", err)
   } else {
     console.log("Return all device observations: ", JSON.stringify(response.data))
     if(response.next_page)
       starfish.getNextPage(response.next_page, .......)
   }
 })

Use `queryDeviceObservations(deviceId, query, callback)` for querying device observations.

Get Next Page

This will return the next page of data up to the limit specified in the original request or default limit of 1MB. Calls the callback with error if next_page is either empty or there is no data.

starfish.getNextPage(next_page, (err, response) => {
   if(err) {
     console.log("Error:", err)
   } else {
     console.log("Return next page data: ", JSON.stringify(response.data))
     if(response.next_page)
       starfish.getNextPage(reseponse.next_page, .....)
   }
 })

Get Device Templates

This will return the list of device templates.

  starfish.getDeviceTemplates((err, data) => {
    if(err) {
      console.log("Error:", err)
    } else {
      console.log("Return devices: ", data)
    }
  })

Response format in case of success:

  {
    deviceTemplates: [
      {
        id: 'someid',
        name: 'templateName',
        sensors: ['few', 'sensors']
      }
    ]
  }

Post Device Template

  const deviceTemplate = {
    deviceTemplate: {
      name: 'templateName',
      sensors: ["few", "sensors"]
    }
  }
  starfish.postDeviceTemplate(deviceTemplate, (err, data) => {
    if(err) {
      console.log("Error:", err)
    } else {
      console.log("Return devices: ", data)
    }
  })

Response format in case of success:

  {
    deviceTemplates: {
        id: 'newlycreateduuid',
        name: 'templateName',
        sensors: ['few', 'sensors']
      }
  }

Edit Device Template

  const deviceTemplate = {
    deviceTemplate: {
      name: 'newName',
      sensors: ["different", "sensors"]
    }
  }
  const templateId = 'existinguuid'
  starfish.putDeviceTemplate(templateId, deviceTemplate, (err, data) => {
    if(err) {
      console.log("Error:", err)
    } else {
      console.log("Return devices: ", data)
    }
  })

Response format in case of success:

  {
    deviceTemplates: {
      id: 'existinguuid',
      name: 'newName',
      sensors: ["different", "sensors"]
    }
  }

Get Static Templates

  starfish.getStaticTemplates(err, data) => {
    if (err) {
      console.log("Error:", err);
    } else {
      console.log("Return devices:", data)
    }
  }

Response format in case of success:

{
  deviceTemplates: [{
    name: 'staticTemplateName',
    sensors: ["few", "sensors"]
  }]
}