Chamada de Serviço através de API

Limite de Uso

A utilização da API de Serviço, possui limitação conforme o plano escolhido pelo usuário. Caso seja o plano de desenvolvimento, o sistema irá limitar ao no máximo 100 requisições por dia, e o máximo de resultado gerado será de 20 informações.

A limitação de utilização será aplicado por toda a API, o limite de resultado será aplicado principalmente nos serviços que se encontram na URL: /service/v1/list/.

Toda requisição gerada sempre será complementado com algumas informações no cabeçalho da resposta, tais como:

HTTP Header Descrição
X-Rate-Limit-Limit A quantidade de requisições realizado no dia.
X-Rate-Limit-Remaining A quantidade de requisições restantes no dia.
X-Rate-Limit-Reset Quantos segundos faltam, em formato EPOCH para resetar o contador de requisição.

Quando o limite de requisições é alcançado o sistema passará a responder as requisições como código HTTP 429 - “Too Many Requests” e será retornado um JSON com a seguinte mensagem de status ao lado.

{"status": "Rate limit exceeded"}

Caso o plano seja diferente de desenvolvimento, a resposta que será colocada no cabeçalho HTTP: X-Rate-Limit-Remaining será -1, ou seja, não possui limitação.

Autenticação

Para realizar a autenticação no serviço o processo é simples, sendo apenas necessário obter o cabeçalho de resposta, e o acesso se dá através do recurso: POST /service/v1/authenticate.

Deverá ser passado como parâmetro na parte --data o valor do e-mail(email) e senha(password), conforme exemplo ao lado.

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

Para conseguir executar o teste, deverá ser utilizado o usuário e senha do usuário responsável pelo projeto.

A resposta da requisição será conforme exemplo ao lado.

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"}

O dado importante para realizar as novas requisições através da API de serviço, será o user-key: 02effd70-56e4-4263-8791-fdc3a717a688, através desse valor será possível chamar todos os demais serviços.

Acessando Listagem de Dados

Dados dos Dispositivos

Para obter os dados dos dispositivos de coleta, utilize o recurso:GET /service/v1/devices.

Conforme dito anteriormente deverá ser utilizado o envio de user-key como cabeçalho para realizar as novas requisições.

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

A resposta será um JSON contendo a lista das informações relativa aos dispositivos de coleta

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

Dados dos Atuadores

Para obter os dados dos dispositivos de coleta, utilize o recurso:GET /service/v1/actuators.

Conforme dito anteriormente deverá ser utilizado o envio de user-key como cabeçalho para realizar as novas requisições.

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

A resposta será um JSON contendo a lista das informações relativa aos dispositivos atuadores

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

Ligando/Desligando Atuador atráves da API

É possível ligar/desligar os atuadores através da API de serviço (não apenas através da dashboard). Existe dois recursos que podem ser utilizado, conforme tabela abaixo:

Recurso Utilidade
GET /service/v1/actuator/on/:serial Ligar o atuador.
GET /service/v1/actuator/off/:serial Desligar o atuador.

Será então necessário, além de passar o cabeçalho user-key o número de série do dispositivo(:serial), conforme exemplos abaixo:

Para ativar:

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

Será retornado um JSON no seguinte formato:

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

Para desativar:

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

Será retornado um JSON no seguinte formato:

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

Para lista os Gatilhos

Para obter os dados dos dispositivos de coleta, utilize o recurso:GET /service/v1/triggers.

Conforme dito anteriormente deverá ser utilizado o envio de user-key como cabeçalho para realizar as novas requisições.

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

A resposta será um JSON contendo a lista das informações relativa aos dispositivos do gatilho.

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

Obtendo dados do Projeto

Informação do Projeto

Para obter informações do projeto, utilize o recurso:GET /service/v1/info/project.

Conforme dito anteriormente deverá ser utilizado o envio de user-key como cabeçalho para realizar as novas requisições.

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

A resposta será um JSON contendo os dados do projeto.

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

A licença poderá ser: dev(Desenvolvedor), startup(StartUp) e pro (Pro).

Limite de Uso

Para obter informações do limite de utilização da camada de serviço, utilize o recurso:GET /service/v1/info/limit_status.

Conforme dito anteriormente deverá ser utilizado o envio de user-key como cabeçalho para realizar as novas requisições.

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

A resposta será um JSON contendo os dados do projeto.

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

Informação do usuário

Para obter informações do usuário, utilize o recurso:GET /service/v1/info/user.

Conforme dito anteriormente deverá ser utilizado o envio de user-key como cabeçalho para realizar as novas requisições.

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

A resposta será um JSON contendo os dados do projeto.

{"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"}

Informação do dispositivo de coleta

Para obter informações do usuário, utilize o recurso:GET /service/v1/info/device/:serial.

Será então necessário, além de passar o cabeçalho user-key o número de série do dispositivo(:serial), conforme exemplos abaixo:

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

A resposta será um JSON contendo os dados do dispositivo de coleta.

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

Informação do atuador

Para obter informações do usuário, utilize o recurso:GET /service/v1/info/actuator/:serial.

Será então necessário, além de passar o cabeçalho user-key o número de série do dispositivo(:serial), conforme exemplos abaixo:

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

A resposta será um JSON contendo os dados do dispositivo de coleta.

{"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"}

Informação do gatilho

Para obter informações do usuário, utilize o recurso:GET /service/v1/info/trigger/:serial.

Será então necessário, além de passar o cabeçalho user-key o número de série do dispositivo(:serial), conforme exemplos abaixo:

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

A resposta será um JSON contendo os dados do dispositivo de coleta.

{"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"}

Criando dispositivo

Criando dispositivo de coleta

É possível criar dispositivos de coleta, baseado nos limites do plano escolhido, através de chamada de serviço.

Conforme dito anteriormente deverá ser utilizado o envio de user-key como cabeçalho para realizar as requisições. É opcional acrescentar, por exemplo, no envio dos dados a descrição (description) do dispositivo.

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

Criando dispositivo gatilho

É possível criar gatilho, baseado nos limites do plano escolhido, através de chamada de serviço.

Conforme dito anteriormente deverá ser utilizado o envio de user-key como cabeçalho para realizar as requisições. É opcional acrescentar, por exemplo, no envio dos dados a descrição (description) do gatilho.

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

Criando dispositivo atuador

É possível criar atuador, baseado nos limites do plano escolhido, através de chamada de serviço.

Conforme dito anteriormente deverá ser utilizado o envio de user-key como cabeçalho para realizar as requisições. É opcional acrescentar, por exemplo, no envio dos dados a descrição (description) do atuador.

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

Removendo Dispositivo

Removendo dispositivo de coleta

Para remover um dispositivo, utilize o recurso:DELETE /service/v1/delete/device/:serial.

Será então necessário, além de passar o cabeçalho user-key o número de série do dispositivo(:serial), conforme exemplos abaixo:

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

Caso a resposta seja dada com sucesso, será dado a seguinte resposta (HTTP 200):

{"status": "Removed Successfully!"}

Em caso de falha, será gerado a seguinte resposta (HTTP 500):

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

Removendo dispositivo gatilho

Para remover um gatilho, utilize o recurso:DELETE /service/v1/delete/actuator/:serial.

Será então necessário, além de passar o cabeçalho user-key o número de série do dispositivo(:serial), conforme exemplos abaixo:

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

Caso a resposta seja dada com sucesso, será dado a seguinte resposta (HTTP 200):

{"status": "Removed Successfully!"}

Em caso de falha, será gerado a seguinte resposta (HTTP 500):

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

Removendo dispositivo atuador

Para remover um gatilho, utilize o recurso:DELETE /service/v1/delete/trigger/:serial.

Será então necessário, além de passar o cabeçalho user-key o número de série do dispositivo(:serial), conforme exemplos abaixo:

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

Caso a resposta seja dada com sucesso, será dado a seguinte resposta (HTTP 200):

{"status": "Removed Successfully!"}

Em caso de falha, será gerado a seguinte resposta (HTTP 500):

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

Listando Informações

Informações coletadas

É possível obter informações dos dados coletados, bem como todo o histórico das informações. Lembrando que o plano desenvolvedor, apenas permite o limite de 20 informações coletadas.

Para que seja possível obter tais informações utiliza-se o recurso:GET /service/v1/list/information/:serial.

Será então necessário, além de passar o cabeçalho user-key o número de série do dispositivo(:serial), conforme exemplos abaixo:

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

A resposta será um JSON contendo os dados do dispositivo de coleta.

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

Existe outros parâmetros que podem ser repassados, para limitar e paginar os resultado, tais como:

Parâmetro Descrição
limit O número máximo de valores a serem exibidos, lembrando que como desenvolvedor esse valor sempre será menor que 20.
skip Quantos registros devem ser "saltados" para contabilizar o limit(parâmetro desconsiderado em caso de plano desenvolvedor).

A ordenação padrão dos dados, será baseado na data de criação dos registros.

Histórico de alteração de atuador/gatilho

É possível obter informações de histórico de alteraçao do atuador/gatilho. Lembrando que o plano desenvolvedor, apenas permite o limite de no máximo 20 informações alteradas.

Para que seja possível obter tais informações utiliza-se o recurso:GET /service/v1/list/history/:serial.

Será então necessário, além de passar o cabeçalho user-key o número de série do dispositivo(:serial), conforme exemplos abaixo:

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

A resposta será um JSON contendo os dados do dispositivo de coleta.

{"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"}]}

Existe outros parâmetros que podem ser repassados, para limitar e paginar os resultado, tais como:

Parâmetro Descrição
limit O número máximo de valores a serem exibidos, lembrando que como desenvolvedor esse valor sempre será menor que 20.
skip Quantos registros devem ser "saltados" para contabilizar o limit(parâmetro desconsiderado em caso de plano desenvolvedor).

A ordenação padrão dos dados, será baseado na data de criação dos registros.