spark-server-api-doc.md

Aeris Spark Server Doc.

aeris' private branch for particle server.

Source repo: https://github.com/spark/spark-server

Postman Link: https://www.getpostman.com/collections/b76bb311a15ddc91579c

Domain: https://particle.aeris.cn

version: 1.0.0

Changes from old api

---

• Login: need client_id & client_secret

Response will have no refresh_token will be deleted
{
  "access_token": "cf9849cd432938ac8e891556381908c3259b9633",
  "token_type": "bearer",
  "expires_in": 7776000
}

• Add isconnected api
• Add server's health check api

Response Introduction

---

Normal Response

• Success

status code: 200

1. {
  "ok": true,
  "msg": "success"
}

2. {
  <data / [data]>
}

• Error

status code: 400/500/...

{
  "ok": false
  "msg": <error: String>
}

Auth2.0 Response

Token did not match

{
  "code": 400,
  "error": "invalid_grant",
  "error_description": "The access token provided is invalid."
}

API

---

Create user

• request

POST /v1/users
Request Body:
{
    "username": <username: String>,
    "password": <password: String>
}

• Success response

statusCode: 200

{
    "ok": true,
    "msg": "success"
}

• Error response

statusCode: 400

{
    "ok": false,
    "msg": <error: String>
}

Login ( get & refresh access_token )

• request

Everytime to login will refresh token.

POST /oauth/token
Header Content-Type: x-www-form-urlencoded
Form 
    username: <username: String>
    password: <password: String>
    grant_type: password
    client_id: HTTP
    client_secret: client_scret_here

• Response

{
  "access_token": "cf9849cd432938ac8e891556381908c3259b9633",
  "token_type": "bearer",
  "expires_in": 7776000
}

Is connected or not

• Request:

GET /v1/isconnected/:coreId?access_token=[access_token]

• Response:

{
  "connected": false
}

Claim Core

• Request:

POST /v1/devices/claim/:coreId?access_token=[access_token]
Request Body:
{
    "coreid": <coreid: String>
}

• Success Response:

Status code: 200

{
    "ok": true,
    "msg" : "success"
}

• Error Response:

Status code: 400

{
    "ok": false,
    "msg": <error: String>
}

Delete Core

• Request:

DELETE /v1/devices/:coreId?access_token=[access_token]

• Response:

{
    "ok": true,
    "msg": "success"
}

Device List

• Request:

GET /v1/devices?access_token=[access_token]

• Response:

[{
      "id": "320048000747343337373738",
      "connected": true
    },
    {
      "id": "40003b001347343339383037",
      "last_heard": null,
      "connected": false
}]

Get One Device's info

• Request:

GET /v1/devices/:coreId?access_token=[access_token]

• Response:

{
    "id": "320048000747343337373738",
    "name": null,
    "connected": true,
    "variables": {},
    "functions": [
      "digitalread",
      "digitalwrite",
      "analogread",
      "analogwrite"
    ]
}

Get core's Func

• Request:

POST /v1/devices/:coreId/:Func?access_token=[access_token]

• Response:

{
    "id": "320048000747343337373738",
    "name": null,
    "last_app": null,
    "connected": true,
    "return_value": -1
}

Set aura's mode

Request:

POST /v1/devices/:coreId/mode?access_token=[access_token]

• args = "manual"
• args = "sleep1","sleep2","sleep3"
• args = "smart"
• args = "Onoff"

Response:

{
  "id": "2e0021001447343339383037",
  "name": null,
  "last_app": null,
  "connected": true,
  "return_value": 0
}

• -1 for error
• Last fan speed for args= “Manual”
• 2 for args= “Smart”
• Last fan speed for sleep
• 0 if off and 1 if on (if argument is “Onoff”)

Set aura's fanspeed

Request:

POST /v1/devices/:coreId/fanset?access_token=[access_token]

args = "1" for off to "255" for max speed

Response:

{
  "id": "2e0021001447343339383037",
  "name": null,
  "last_app": null,
  "connected": true,
  "return_value": 1
}

• 1 if fan is set to desired value
• -1 if fan is not set to desired value

Set aura's snooze

Request:

POST /v1/devices/:coreId/snooze?access_token=[access_token]

args = "1" for switching on snooze
args = "-1" for switching off snooze

Return:

• 1 if snooze is switched on
• 2 if snooze is switched off
• -1 in case of error

Set a new program for aura

Request:

POST /v1/devices/:coreId/dayprogram?access_token=[access_token]

args="xxxDDDDDDDHHMMhhmmP"

• xxx – Program ID
• D - Day [1-7]
• HH – Hour start [00-24]
• MM – Minute start [00-59]
• hh – hour end [00-24]
• mm – minute end [00-59]
• P - program [0-9]

Return:

• 1 if sent program is valid
• -1 if sent program is invalid

Get core's Var

• Request:

GET /v1/devices/:coreId/:var?access_token=[access_token]

• Error Response:

{
  "ok": false,
  "msg": "Variable not found"
}

Get aura's stats

Request:

GET /v1/devices/:coreId/stats?access_token=[access_token]

Response:

{
  "cmd": "VarReturn",
  "name": "stats",
  "result": "{\"PM\": 0, \"AQI\": 0, \"Mode\": 1, \"SnzMin\": 0, \"SnzSec\": 0, \"fan\": 1, \"fil\": 179.888000, \"on\": 1, \"pwr\": 3.725490, \"apwr\": 69.060458}",
  "coreInfo": {
    "connected": true
  }
}

• PM
• AQI
• Mode

  1 for manual 2 for smart 3 for sleep

• Snz: Snooze time left

  (0 when snooze is off)

• fan: Current fan speed (Can be checked when in sleep or manual mode)
• fil: Remaining filter life

  (180 is maximum, to get percentage -> fil/180)

• on: Informs if device on or off

  (Connectivity still on even if device is off) 1 for on -1 for off

• pwr: current power consumption in W
• pwra: Average power consumption in W

Request:

GET /v1/devices/:coreId/alldata?access_token=[access_token]

Response:

{
  "cmd": "VarReturn",
  "name": "alldata",
  "result": "{\"PM\": 0, \"O3\": 4.000000, \"NO2\": 0.000000, \"CO\": 12.000000, \"temp\": 31.185810, \"hum\": 13.325256}",
  "coreInfo": {
    "connected": true
  }
}

GET ALL Event

• Request:

GET /v1/events?access_token=[super_access_token]

GET ALL One Event

• Request:

GET /v1/events/:eventName?access_token=[access_token]

GET My Event

• Request:

GET /v1/devices/events?access_token=[access_token]

GET My One Event

• Request:

GET /v1/devices/events/:eventName?access_token=[access_token]

One core's event

• Request:

GET /v1/devices/:coreId/events?access_token=[access_token]

One core's one Event

• Request:

GET /v1/devices/:coreId/events/:eventName?access_token=[access_token]

Add A Event

• Request:

POST /v1/devices/events?access_token=[access_token]
BODY:
{
    "name": "Test",
    "data": "Data",
    "coreid": "320048000747343337373738"
}

• Response:

{
  "ok": true,
  "msg": "success",
  "data": true
}