Commit 8e76c459 authored by Nelso Jost's avatar Nelso Jost

Update README.md to include API usage instructions

parent 85c6f9c1
# emm-webapp
Este projeto consiste em uma aplicação web responsável pelo armazenamento e gerenciamento dos dados meteorológicos abertos do projeto EMM, atualmente publicada em:
Aplicação web dedicada ao armazenamento de dados meteorológicos do projeto [Estações Meteorológicas Modulares](http://cta.if.ufrgs.br/projects/estacao-meteorologica-modular/wiki/Wiki) (EMM).
Atualmente publicada em:
* [dados.cta.if.ufrgs.br/emm](http://dados.cta.if.ufrgs.br/emm/)
O protótipo inicial conta com uma [API RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) simples, desenvolvida em [Flask](http://flask.pocoo.org/), para coletar dados enviados pelo software [loggger](https://git.cta.if.ufrgs.br/meteorolog/logger) e armazená-los em um servidor do [CTA](http://cta.if.ufrgs.br/), na UFRGS.
## API
A webapp oferece uma RESTful API para envio e acesso aos dados armazenados. Funciona assim: envia-se uma requisição HTTP contendo um objeto JSON (header `content-type: application/json`) para a URL; a webapp responde com outro objeto JSON.
> Note: Objetos JSON são análogos (em geral) aos dicionários de Python.
* No advento de erros, o seguinte JSON será retornado:
** `{"Error": message}`
### /get/boardhash (POST)
Permite ao usuário obter a *hash* de autenticação da sua própria estação. Esta *hash* (string de 128 caracteres) deve ser utilizada para autenticar o envio de dados pela API.
* ENTRADA:
```
{
"board_id": int,
"user_password": str
}
```
* SAÍDA:
```
{
"board_hash": str
}
```
### /post/rawsensordata (POST)
Permite ao usuário enviar dados para sua estação.
Naturalmente, a tarefa pode ser automatizada por um data logger, tal como [emm-logger](https://git.cta.if.ufrgs.br/meteorolog/logger).
* ENTRADA:
```
{
"board_hash": str, # hash de autenticação de usuário
"data": # dados a serem guardados
[
{
"datetime": # chave primária da tabela
{
"value": str, # ex: 2016-08-10-17-20-00
"format": str, # ex: %Y-%m-%d-%H-%M-%S
"source": str # ex: "RTC", "WEB", "SYS"
},
"sensors": # N sensores lidos
{
"name1": number, "name2": number, ..., "nameN": number
}
}
]
}
```
* SAÍDA:
```
{
"success": "{N} new points were saved on the board."
}
```
### /get/csv/rawsensordata/<int:board_id>
Permite a qualquer pessoa obter os dados da estação identificada por `<int:board_id>`.
* Retorna um arquivo `.csv` contendo TODOS os dados da estação, no formato:
```
DATETIME,sensor1,sensor2,...,sensorN
```
Esta é uma requisição GET simples (não requer JSON) e pode ser feita em um web browser quaquer.
#### Utilizando a API RESTful
Há duas opções básicas para interagir com a API:
* **Curl**
```
$ curl -i -H 'content-type: application/json' -X POST
-d '{"board_id": 3,"user_password": "1234"}'
http://dados.cta.if.ufrgs.br/emm/api/get/boardhash
HTTP/1.1 200 OK
Server: nginx/1.6.2
Date: Thu, 25 Jun 2011 21:45:12 GMT
Content-Type: application/json
Content-Length: 88
Connection: keep-alive
Set-Cookie: session=eyJfaWQiOiJhMjUwZjVhMDViMjdkMGNkOTUzN2Q4YTViYWQzODFiMiJ9.CqDqWA.5TmPTa9zus8ZVo0avVnwz-O4-Dc; Domain=.dados.cta.if.ufrgs.br; HttpOnly; Path=/
{
"board_hash": "pbkdf2:sha1:1000$rT98ercf$bf77e6ca081826cbf9fc0fab23cb93bf17fe598b"
}
```
* Python + excelente biblioteca **requests** (instale via `pip3`).
```
>>> import requests
>>> url = 'http://dados.cta.if.ufrgs.br/emm/api/get/boardhash'
>>> d = {'board_id': 3, 'user_password': '1234'}
>>> r = requests.post(url, json=d)
>>>> r
<Response [200]> # 200 significa "sucesso"
>>> r.json()
{'board_hash': 'pbkdf2:sha1:1000$rT98ercf$bf77e6ca081826cbf9fc0fab23cb93bf17fe598b'}
```
## Instalação e manutenção
## Instalação e uso
Seguem abaixo instruções para instalação e manutenção da webapp em seu próprio servidor.
O projeto inclui um arquivo `Makefile` contendo diversos comandos rápidos para realização das principais operações de instalação e manutenção da web app e servidor de dados.
O projeto inclui um arquivo `Makefile` contendo diversos comandos simples para manutenção no diretório raiz. É preciso estar neste diretório para executar:
Para executar comandos do `Makefile` é preciso estar dentro da raiz do repositório:
```
~/emm-webapp $ ls
app doc Makefile production requirements.pip
data logs manage.py README.md tests
~/emm-webapp $ make <comando>
~/emm-webapp $ make <command>
```
Execute `make` ou `make help` para obter uma lista dos comandos disponíveis.
Execute simplesmente `make` ou `make help` para obter uma lista de todos os comandos disponíveis e uma breve descrição.
### 1. Preparando ambiente de execução
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment