O CaUMa possui uma API REST que permite que outros aplicativos possam interagir com o serviço de forma bem definida. Podendo ser utilizada na integração com ferramenta de proteção dos usuários, como anti-spam.
Funcionalidades
- Autenticação dos usuários da API
- Requisição feita via HTTP POST
- Dados transmitidos utilizando formato JSON
- Possibilidade de consultar múltiplas numa única requisição
- Download da lista de URLs com possibilidade de filtros
Consulta
Uma consulta deve ser realizada para o endereço https://cauma.pop-ba.rnp.br/api/v2.0/find utilizando o método HTTP POST com os seguintes dados:
- Cabeçalho HTTP indicando que o conteúdo possui formato JSON
Content-Type: application/json
Conteúdo da mensagem HTTP contendo objeto JSON com informações de autenticação do usuário e uma lista de URLs a serem analisadas.
{
"client": {
"clientLogin": <login>,
"clientKey": "<key>"
},
"threatEntries": ["<URL1>","<URL2>","<URL3>"]
}
Resposta
Já as consultas autenticadas com sucesso receberão uma resposta HTTP com status 200. O conteúdo da resposta é um objeto JSON com uma lista com true para as URLs encontradas e false para as URLs não encontradas, cada item da lista corresponde a uma URL submetida na consulta.
{
"data": {
"threatResults": [true, false, true]
}
}
Exemplos
HTTPie
Criar arquivo consulta.json no formato descrito na seção acima e executar o seguinte comando.
$ http https://cauma.pop-ba.rnp.br/api/v2.0/find < consulta.json
Python
import requests
import json
def run_post():
url = 'https://cauma.pop-ba.rnp.br/api/v2.0/find'
headers = {"Content-Type": "application/json"}
data = {
"client": {"clientLogin": <login>, "clientKey": "<key>"},
"threatEntries": ["<URL1>","<URL2>","<URL3>"]
}
return requests.post(url, json=data, headers=headers)
print json.dumps(run_post().json())
cURL
Criar arquivo consulta.json no formato descrito na seção acima e executar o seguinte comando.
$ curl -i -H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST -d "$(cat consulta.json)" \
https://cauma.pop-ba.rnp.br/api/v2.0/find
Download
É possível baixar as URLs contidas na base do CaUMa para consulta local. Para isso, uma consulta deve ser realizada para o endereço https://cauma.pop-ba.rnp.br/api/v2.0/download utilizando o método HTTP POST e os dados de autenticação no corpo da requisição. Opcionalmente, é possível limitar o conjunto de dados retornados através dos parâmetros abaixo:
- page - utilizado para controlar a paginação do conjunto de dados retornado, os valores aceitos são números inteiros.
- limit - define o número máximo de URLs retornadas, os valores aceitos são números inteiros.
- start - restringe o conjunto de dados a URLs inseridas a partir da data especificada, aceita o formato de data definido na RFC 3339, sendo o horário opcional (e.g. 1996-12-19 ou 1996-12-19T16:39:57-08:00).
- end - restringe o conjunto de dados a URLs inseridas a até da data especificada, aceita o mesmo formato de data especificado para o parâmetro start.
Resposta
O servidor retorna uma lista paginada das URLs e os dados associdos a cada uma delas. A resposta é limitada a no máximo 1000 URLs por uma questão de performance e as URLs adicionais podem ser obtidas através do parâmetro page. Os dados são ordenados pela data de inserção em ordem decrescente, assim as URLs mais recentes serão retornadas na primeira página.
