Skip to content

RESTful API's

Jump to bottom
Sea Yo edited this page Mar 20, 2016 · 20 revisions

Admin Endpoints

Login Eywa as Admin

This endpoint is used to login Eywa, and get the auth_token for later communication.

request

  curl -XGET -u root:waterISwide http://<eywa_server>:<eywa_port>/admin/login

response

{
  "auth_token":"qUGsp3hRAHOnhd2Dg9xyc69AMShbkAdWJ5HUL4WmN4EKV2CDqe09kqdecEs6FD6ieJVnHqaKr9QMS2p0qFrjk2hLN-3uA-7TZe_HveOmUcd4txVjT45ES_O9rj8MXXYfKJoEMNxX4eQWlbqeDmA1bDUMzzuPAb74099yHOtB6goVB4M6Yw_T8u0gn3PYYBAwzl2ydxioDJajCSWCLjmk6nJAWIuOfjNyA1s-WOgjMmqK9ze9k1nFzGbeveMofaA5gw3Pkwj4cQgp4IUPGLjSJ2w5y3B3NBVXkJwe-P32_1mOnilgBuYtu3OEHV02dxqgdvAOxvYWdUhlcBPf3B2DJ_RvNGcl0hCde2HWdmvmgm-ZcJf-I7hgNjTFDiE_SeKgDS_cqMdkziiv6mWhQwTEGhO9i8OVVU2d_SLQP0uUxRq_v2bAsh8IQC-hCxbOjKN-3EQmfqlCSjua9uYeh570EmVXpEzCeExlsq9YNOB0YyuR-_mdT2jggyTa3es4XInld5n7-e6jdpS-1lHKxeSMkSK-sCsNSQpKHEnGwIsj",
  "expires_at":1458111140885
}

This returns the auth_token and its expiration time. By default, a auth_token expires in 24 hours. You can update this setting in configuration file of via API dynamically.

Get current Settings

request

  curl -XGET -H 'Authentication: <auth_token>' http://<eywa_server>:<eywa_port>/admin/configs

response

{
  "service": {
    "host": "localhost",
    "api_port": 8080,
    "device_port": 8081
  },
  "security": {
    "dashboard": {
      "username": "root",
      "token_expiry": "24h0m0s"
    }
  },
  "connections": {
    "registry": "memory",
    "nshards": 8,
    "init_shard_size": 1024,
    "http": {
      "timeouts": {
        "long_polling": "10m0s"
      }
    },
    "websocket": {
      "request_queue_size": 8,
      "timeouts": {
        "write": "4s",
        "read": "5m0s",
        "request": "4s",
        "response": "16s"
      },
      "buffer_sizes": {
        "write": 1024,
        "read": 1024
      }
    }
  },
  "indices": {
    "disable": false,
    "host": "localhost",
    "port": 9200,
    "number_of_shards": 8,
    "number_of_replicas": 0,
    "ttl_enabled": false,
    "ttl": "0"
  },
  "database": {
    "db_type": "sqlite3",
    "db_file": "/var/eywa/eywa.db"
  },
  "logging": {
    "eywa": {
      "filename": "/var/eywa/eywa.log",
      "maxsize": 1024,
      "maxage": 7,
      "maxbackups": 5,
      "level": "info",
      "buffer_size": 512
    },
    "indices": {
      "filename": "/var/eywa/indices.log",
      "maxsize": 1024,
      "maxage": 7,
      "maxbackups": 5,
      "level": "warn",
      "buffer_size": 512
    },
    "database": {
      "filename": "/var/eywa/db.log",
      "maxsize": 1024,
      "maxage": 7,
      "maxbackups": 5,
      "level": "warn",
      "buffer_size": 512
    }
  }
}

Some security settings are hidden from the response.

Update the Settings Dynamically

request

curl -XPUT -H 'Authentication: <auth_token>' "http://<eywa_server>:<eywa_port>/admin/configs" -d '{
  "connections": {
    "http": {
      "timeouts": {
        "long_polling": "300s"
      }
    }
  }
}'

This updates the http long-polling timeouts dynamically. response

It returns the similar response as getting the current settings, with updated values.

If you are updating username or password, upon success, you will be required to login again with the updated credentials.

Note that while dynamic settings allow you to change Eywa's behavior without restarting the server, all the updated settings are not persisted. Once Eywa is restarted, they will be gone. So please always make sure your configuration file is updated too.

List Channels

List all the defined channels with brief information.

request

  curl -XGET -H 'Authentication: <auth_token>' http://<eywa_server>:<eywa_port>/admin/channels

response

[
  {
    "id": "GDE3N17PA5gXAlVj",
    "name": "hotel monitoring",
    "description": "This is a channel created for monitoring hotel."
  },
  {
    "id": "B0bnv47Mm7Gdj63w",
    "name": "test123",
    "description": "test12333"
  }
]

Show Channel details

request

  curl -XGET -H 'Authentication: <auth_token>' http://<eywa_server>:<eywa_port>/admin/channels/<channel_id>

response

{
  "id": "GDE3N17PA5gXAlVj",
  "name": "hotel monitoring",
  "description": "This is a channel created for monitoring hotel.",
  "tags": [
    "hotel",
    "building",
    "floor",
    "room",
    "room_type"
  ],
  "fields": {
    "brightness": "int",
    "co2": "int",
    "cooler": "boolean",
    "humidity": "int",
    "light1": "boolean",
    "light2": "boolean",
    "pm2_5": "int",
    "sound": "int",
    "temperature": "float"
  },
  "access_tokens": [
    "abcdefg"
  ]
}

Delete Channel

In development mode, you may want to delete the created channel. However, if your channels are in production mode, which means you have devices that are connection to Eywa through this channel, deleting the channel will result in connection failures.

request

  curl -XDELETE -H 'Authentication: <auth_token>' http://<eywa_server>:<eywa_port>/admin/channels/<channel_id>

response

  200 OK

Create a Channel

request

curl -XPOST -H 'Authentication: <auth_token>' "http://<eywa_server>:<eywa_port>/admin/channels" -d'
{
  "name": "hotel monitoring",
  "description": "This is a channel created for monitoring hotel.",
  "tags": [
    "hotel",
    "building",
    "floor",
    "room",
    "room_type"
  ],
  "fields": {
    "brightness": "int",
    "co2": "int",
    "cooler": "boolean",
    "humidity": "int",
    "light1": "boolean",
    "light2": "boolean",
    "pm2_5": "int",
    "sound": "int",
    "temperature": "float"
  },
  "access_tokens": [
    "abcdefg"
  ]
}
'

response

{
  "id": "GDE3N17PA5gXAlVj",
  "name": "hotel monitoring",
  "description": "This is a channel created for monitoring hotel."
}

Don't worry about all these complex data structure, our admin panel and command line tool will take care of all these.

Update a Channel

request

curl -XPUT -H 'Authentication: <auth_token>' "http://<eywa_server>:<eywa_port>/admin/channels/<channel_id>" -d'
{
  "name": "updated name"
}
'

This simply updates the channel name.

response

  200 OK

Query Eywa

This is explained in detail in the section of Query Eywa

Get Current Connection Count

request

  curl -XGET -H 'Authentication: <auth_token>' "http://<eywa_server>:<eywa_port>/admin/connections/count"

response

{"count": 500}

Get a connection status for a specific device

request

curl -XGET -H 'Authentication: <auth_token>' "http://<eywa_server>:<eywa_port>/admin/channels/<channel_id>/devices/<device_id>/status"

response

{
  "channel": "hotel monitoring",
  "status": "online",
  "identifier": "marriott-building-1-floor-1-room-2"
}

You can even ask for connection history by appending history=true parameter. Eywa returns the most recent 100 connection activities for that device

curl -XGET -H 'Authentication: <auth_token>' "http://<eywa_server>:<eywa_port>/admin/channels/<channel_id>/devices/<device_id>/status?history=true"

response

{
  "channel": "hotel monitoring",
  "status": "offline",
  "identifier": "marriott-building-1-floor-1-room-2",
  "histories": [
    {
      "activity": "disconnect",
      "timestamp": "2016-03-12T09:38:27.056Z",
      "connection_type": "websocket",
      "duration": 125309
    },
    {
      "activity": "connect",
      "timestamp": "2016-03-12T09:36:21.745Z",
      "connection_type": "websocket"
    },
    {
      "activity": "disconnect",
      "timestamp": "2016-03-12T07:54:47.65Z",
      "connection_type": "websocket",
      "duration": 96249
    },
    {
      "activity": "connect",
      "timestamp": "2016-03-12T07:53:11.4Z",
      "connection_type": "websocket"
    }
  ]
}

Send QoS=0 Signal to Device

request

  curl -XPOST -H 'Authentication: <auth_token>' "http://<eywa_server>:<eywa_port>/admin/channels/<channel_id>/devices/<device_id>/send" -d '
 this can be a binary data
'

response

Eywa will return 200 if message is sent. Or return error message if device is not online.

Send QoS=1 Signal to Device

request

  curl -XPOST -H 'Authentication: <auth_token>' "http://<eywa_server>:<eywa_port>/admin/channels/<channel_id>/devices/<device_id>/request" -d '
 this can be a binary data
'

response

whatever response from the device

Note this is a QoS=1 message and will only be available for websocket connections.

API Endpoints

We strongly go against to expose these API endpoints directly to your mobile app, because it makes Eywa vulnerable for various of attacks. These endpoints are designed for your application layer services inside of same virtual private network. You should do more authentication, encryption in your application layer instead of relying everything on Eywa.

Currently 5 API endpoints are exposed

GET  http://<eywa_server>:<eywa_port>/api/channels/<channel_id>/value
GET  http://<eywa_server>:<eywa_port>/api/channels/<channel_id>/series
GET  http://<eywa_server>:<eywa_port>/api/channels/<channel_id>/devices/<device_id>/status"
POST http://<eywa_server>:<eywa_port>/api/channels/<channel_id>/devices/<device_id>/send
POST http://<eywa_server>:<eywa_port>/api/channels/<channel_id>/devices/<device_id>/request"

Their responses are exactly the same as admin endpoints. However, to make these API calls, instead of login every 24 hours, you will need to carry a Api-Token header in each request. The accepted api token can be configured in configuration file and updated dynamically.

Clone this wiki locally