Call service through API

Use Limit

The use of the Service API, has limitations as chosen by the user plane. If the development plan, the system will limit the maximum in 100 requests a day, and the maximum income generated will be 20 information.

The limitation of use will be applied throughout the API, the result limit is mainly applied in the services that are at URL: /service/v1/list/.

Every request will be generated always complemented with some information in the header of the response, such as:

HTTP Header Description
X-Rate-Limit-Limit The number of requests held on.
X-Rate-Limit-Remaining The amount of remaining requests on.
X-Rate-Limit-Reset How many seconds are missing in EPOCH format to reset the request counter.

When the requests limit is reached the system will respond to the requests as code HTTP 429 - “Too Many Requests” and it will return a JSON with the following status message next.

{"status": "Rate limit exceeded"}

If the plan is different from development, the answer is placed in the HTTP header: X-Rate-Limit-Remaining will -1, so, has no limitation.

Authentication

To perform authentication service in the process is simple, requiring only get the response header, and the access is by using: POST /service/v1/authenticate.

It should be passed as a parameter in the --data the value of e-mail (email) and password (password) as example here.

$ curl --data "email=suporte@webonesystem.com.br&password=senha" -i -X POST https://guardiaocloud.com.br/service/v1/authenticate

To be able to run the test, it should be used the user and password of the user responsible for the project.

The response of the request will be as example here.

HTTP/1.1 200 OK
Server: nginx/1.4.6 (Ubuntu)
Date: Thu, 28 May 2015 13:31:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 128
Connection: keep-alive
X-powered-by: Guardiao Cloud
x-request-id: 02effd70-56e4-4263-8791-fdc3a717a688
set-cookie: i18next=en; path=/; expires=Sat, 28 May 2016 13:31:23 GMT
set-cookie: connect.sid=s%3AD2XSq2sPF8ntQBLlBBHRGy-ADYP0u_C1.iNU2Zpr42uzg%2FMI67GYnBA0Xk%2FmmK4lUjnXr%2FPNL6Lc; Path=/; HttpOnly
Vary: X-HTTP-Method-Override, Accept-Encoding
user-key: 2a19f1e3-a0f5-4bd4-acb0-d2bd26138533
ETag: W/"80-bf1b4b1c"

{"email":"suporte@webonesystem.com.br","firstName":"webone","lastName":"system","apiKey":"497aa991-d8e6-4bb6-ad17-f01a13648333"}

The important thing to make new requests through the Service API will be user-key: 02effd70-56e4-4263-8791-fdc3a717a688, through this value you can call all other services.

Accessing Data Listing

Devices of data

For the data collection devices, use the feature:GET /service/v1/devices.

As mentioned above should be used to send user-key as a header to make new requests.

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/devices

The response will be a JSON containing the list of information relating to collection devices

[{"serial":"IOTWBS0001","description":"Coleta","data":"{\"humidade\":30,\"temperatura\":10,\"luminosidade\":15}","dateCollect":"2015-05-26T11:13:24.405Z"}]

Actuators data

For the data collection devices, use the feature:GET /service/v1/actuators.

As mentioned above should be used to send user-keyas a header to make new requests.

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/actuators

The response will be a JSON containing the list of information concerning actuators devices

[{"serial":"IOTWBS0003","description":"Atuador","state":false,"dateConnect":"2015-05-26T12:06:12.582Z","dateUpdated":"2015-05-26T12:06:12.582Z"}]

Powering On / Off Actuator Through API

It is possible to turn on / off the actuators through service API (not just through the dashboard). There are two features that can be used, as follows:

Resource Utility
GET /service/v1/actuator/on/:serial Connect the actuator.
GET /service/v1/actuator/off/:serial Turn off the actuator.

It will then be necessary, in addition to passing the header user-key The device serial number (:serial), as examples below:

To activate:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/actuator/on/IOTWBS0003

A JSON will be returned in the following format:

{"serial":"IOTWBS0003","state":true}

To turn off:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/actuator/off/IOTWBS0003

A JSON will be returned in the following format:

{"serial":"IOTWBS0003","state":false}

To list the Triggers

For the data collection devices, use the feature:GET /service/v1/triggers.

As mentioned above should be used to send user-key as a header to make new requests.

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/triggers

The response will be a JSON containing the list of information on the trigger devices.

[{"serial":"IOTWBS0002","description":"gatilho","state":false,"dateConnect":"2015-05-26T11:51:48.177Z","dateUpdated":"2015-05-26T11:52:00.925Z"}]

Getting Project data

Project Information

For project information, use the feature:GET /service/v1/info/project.

As mentioned above should be used to send user-key as a header to make new requests.

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/info/project

The response will be a JSON containing project data.

{"name":"WebOne Suporte","apiKey":"497aa991-d8e6-4bb6-ad17-f01a13648333","prefix":"IOTWBS","dateCreated":"2015-05-22T19:37:48.780Z","countDevices":,"totalDevices":3,"license":"dev"}

The license may be: dev (Developer) startup (StartUp) and pro (Pro).

Use Limit

For limit the information to use the service layer, use the feature:GET /service/v1/info/limit_status.

As mentioned above should be used to send user-key as a header to make new requests.

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/info/limit_status

The response will be a JSON containing project data.

{"apiLimit":100,"apiUsage":7,"dateUsage":"2015-05-28T13:48:13.322Z"}

User Information

For user information, use the feature:GET /service/v1/info/user.

As mentioned above should be used to send user-key as a header to make new requests.

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/info/user

The response will be a JSON containing project data.

{"hashKey":"2a19f1e3-a0f5-4bd4-acb0-d2bd26138533","timezone":"Brazil/Recife","numberLogin":6,"dateLastLogin":"2015-05-28T13:47:45.375Z","lastName":"System","firstName":"Webone","cellPhone":"+55 (84) 9999-9999","email":"suporte@webonesystem.com.br"}

Collecting device information

For user information, use the feature:GET /service/v1/info/device/:serial.

It will then be necessary, in addition to passing the header user-key The device serial number (:serial), as examples below:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/info/device/IOTWBS0001

The response will be a JSON containing the data collection device.

{"serial":"IOTWBS0001","description":"Coleta","dateCreated":"2015-05-25T11:45:06.162Z"}

Actuator information

For user information, use the feature:GET /service/v1/info/actuator/:serial.

It will then be necessary, in addition to passing the header user-key The device serial number (:serial), as examples below:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/info/actuator/IOTWBS0003

The response will be a JSON containing the data collection device.

{"serial":"IOTWBS0003","description":"Atuador","tags":["temp","temp","casa","casa"],"dateUpdated":"2015-05-28T14:14:23.724Z","dateConnect":"2015-05-26T12:06:12.582Z","state":true,"dateCreated":"2015-05-25T12:47:31.322Z"}

Trigger information

For user information, use the feature:GET /service/v1/info/trigger/:serial.

It will then be necessary, in addition to passing the header user-key The device serial number(:serial), as examples below:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/info/trigger/IOTWBS0002

The response will be a JSON containing the data collection device.

{"serial":"IOTWBS0002","description":"Gatilho","dateConnect":"2015-05-26T11:51:48.177Z","dateUpdated":"2015-05-26T11:52:00.925Z","state":false,"dateCreated":"2015-05-25T11:54:52.778Z"}

Creating device

Creating collection device

You can create collection devices, based on plan limits chosen through service call.

As mentioned above should be used to send user-key as a header to make requests. It is optional to add, for example, sending the data description (description) the device.

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" --data "description=Ambiente" -X POST https://guardiaocloud.com.br/service/v1/create/device

Creating trigger device

You can create trigger, based on plan limits chosen through service call.

As mentioned above should be used to send user-key as a header to make requests. It is optional to add, for example, sending the data description (description)trigger.

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" --data "description=Sensor" -X POST https://guardiaocloud.com.br/service/v1/create/trigger

Creating actuator device

You can create actuator, based on the plan limits chosen through service call.

As mentioned above should be used to send user-key as a header to make requests. It is optional to add, for example, sending the data description (description) the actuator.

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" --data "description=Lampada" -X POST https://guardiaocloud.com.br/service/v1/create/actuator

Removing Device

Removing collection device

To remove a device, use the feature:DELETE /service/v1/delete/device/:serial.

It will then be necessary, in addition to passing the headeruser-key The device serial number(:serial), as examples below:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X DELETE https://guardiaocloud.com.br/service/v1/delete/device/IOTWBS0001

If the answer is successfully given, will be given the following response (HTTP 200):

{"status": "Removed Successfully!"}

In case of failure, it will be generated the following response (HTTP 500):

{"status": "Failed to Remove Device"}

Removing trigger device

To remove a trigger, use the feature:DELETE /service/v1/delete/actuator/:serial.

It will then be necessary, in addition to passing the header user-key The device serial number (:serial),as examples below:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X DELETE https://guardiaocloud.com.br/service/v1/delete/actuator/IOTWBS0003

If the answer is successfully given, will be given the following response (HTTP 200):

{"status": "Removed Successfully!"}

In case of failure, it will be generated the following response (HTTP 500):

{"status": "Failed to Remove Device"}

Removing actuator device

To remove a trigger, use the feature:DELETE /service/v1/delete/trigger/:serial.

It will then be necessary, in addition to passing the header user-key The device serial number(:serial), as examples below:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X DELETE https://guardiaocloud.com.br/service/v1/delete/trigger/IOTWBS0003

If the answer is successfully given, will be given the following response (HTTP 200):

{"status": "Removed Successfully!"}

In case of failure, it will be generated the following response (HTTP 500):

{"status": "Failed to Remove Device"}

listing Information

information collected

You can obtain information on the data collected, as well as the entire history of information. Recalling that the developer plan allows only limit 20 information collected.

To be able to obtain such information is used the resource:GET /service/v1/list/information/:serial.

It will then be necessary, in addition to passing the header user-key The device serial number(:serial), as examples below:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/list/information/IOTWBS0001

The response will be a JSON containing the data collection device.

{"searchParams":{"limit":20,"sort":{"dateCreated":-1}},"result":[{"data":{"humidity":10,"temperature":30,"luminosidade":"15"},"dateCollect":"2015-05-25T14:18:33.763Z"},{"data":{"humidity":10,"temperature":30,"luminosidade":"15"},"dateCollect":"2015-05-25T14:18:23.876Z"},{"data":{"humidity":10,"temperature":30,"luminosity":"15"},"dateCollect":"2015-04-14T14:05:56.467Z"},{"data":{"humidity":10,"temperature":30,"luminosity":"15"},"dateCollect":"2015-04-13T23:26:35.597Z"}]}

There are other parameters that can be passed to limit and paginate results such as:

Parameter Description
limit The maximum number of values to be displayed, noting that as a developer this value will always be less than 20.
skip How many records should be "jumped" to account for the limit (parameter overlooked in developer plane case).

The default ordering of data, will be based on the date of creation of the records.

Change History actuator / trigger

You can obtain alteration history information Actuator / trigger. Recalling that the developer plan only allows maximum limit in 20 changed information.

To be able to obtain such information is used the feature:GET /service/v1/list/history/:serial.

It will then be necessary, in addition to passing the header user-key The device serial number(:serial), as examples below:

$ curl -H "user-key:2a19f1e3-a0f5-4bd4-acb0-d2bd26138533" -X GET https://guardiaocloud.com.br/service/v1/list/history/IOTWBS0002

The response will be a JSON containing the data collection device.

{"searchParams":{"limit":20,"sort":{"dateCreated":-1}},"result":[{"dateCreated":"2015-04-08T18:16:51.369Z","actualState":"on","changedBy":"","changeOrigin":"Interface Web"},{"dateCreated":"2015-04-08T18:16:49.819Z","actualState":"off","changedBy":"","changeOrigin":"Interface Web"},{"dateCreated":"2015-04-08T18:14:51.125Z","actualState":"on","changedBy":"","changeOrigin":"Interface Web"},{"dateCreated":"2015-04-08T18:14:35.100Z","actualState":"off","changedBy":"","changeOrigin":"Interface Web"},{"dateCreated":"2015-03-04T14:56:25.251Z","actualState":"on","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:56:16.250Z","actualState":"on","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:56:11.868Z","actualState":"on","changedBy":"","changeOrigin":"Interface Web"},{"dateCreated":"2015-03-04T14:55:57.747Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:55:51.245Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:55:48.203Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:55:43.783Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:55:43.779Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:55:38.737Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:55:23.600Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:47:17.939Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:45:59.506Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:43:33.504Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:43:33.503Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:43:33.500Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"},{"dateCreated":"2015-03-04T14:43:33.496Z","actualState":"off","changedBy":"","changeOrigin":"CoAP GET"}]}

There are other parameters that can be passed to limit and paginate results such as:

Parameter Description
limit The maximum number of values to be displayed, noting that as a developer this value will always be less than 20.
skip How many records should be "jumped" to account for the limit (parameter overlooked in developer plane case).

The default ordering of data, will be based on the date of creation of the records.