API

Essa página traz informações sobre a nossa API, disponível em /api. Exceto pelo health check, para acesso é necessário um token.

Infelizmente não podemos abrir a nossa API por hora, devido a restrições na nossa infraestrutura (um volume de requisições que não poderíamos manter). Por isso o uso da API ficará restrito aos projetos do Dados Abertos de Feira. Caso tenha uma ideia e queira discutir mais sobre isso, envie um e-mail para o projeto: dadosabertosdefeira@gmail.com.

Autenticação

A autenticação é feita através de um token. Três endpoints estão disponíveis para o fluxo de autenticação:

• api/token/
• api/token/refresh/
• api/token/verify/

Obtendo um token

Para obter um token é necessário ter um usuário na administração dessa aplicação. Você pode criar um através do comando make createsuperuser e então usar as credenciais para solicitar um token:

curl -i \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{ "username": "nome_do_usuario", "password": "senha_do_usuario" }' http://localhost:8000/api/token/

A resposta deve ser algo parecido com isso:

{
    "refresh": "xxx",
    "access": "yyy"
}

Utilize o valor retornado em access como cabeçalho de autenticação na próxima requisição, como no exemplo abaixo:

curl -i -H "Content-Type: application/json" -H "Authorization: Bearer yyy" http://localhost:8000/api/

Por padrão todas as rotas criadas na API só poderão ser acessadas com autenticação, apenas o health check tem acesso público.

Atualizando o token

Para atualizar um token, use o valor do campo refresh obtido no passo anterior.

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"refresh":"xxx"}' \
  http://localhost:8000/api/token/refresh/

O retorno é algo como:

{"access": "eee"}

Verificando o token

Você pode checar se o token está ok antes de atualizá-lo:

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"token": "eee"}' http://localhost:8000/api/token/verify/

Caso tudo esteja ok, você vai ver na resposta um {}. Se não, uma resposta como essa:

{"detail":"Token is invalid or expired","code":"token_not_valid"}

Configurações

Foram disponibilizadas variáveis de ambiente para setar o tempo de vida dos tokens. São elas:

• ACCESS_TOKEN_LIFETIME_IN_MINUTES (por padrão 24 horas)
• REFRESH_TOKEN_LIFETIME_IN_MINUTES (por padrão 24 horas)

Endpoints

Todos os endpoints estão sob api/. Os resultados são paginados (50 itens por página). Exemplo de payload:

{
    "count": 249,
    "next": "http://localhost:8000/api/city-council/agenda/?page=2",
    "previous": null,
    "results": [...]
}

Endpoint	Propósito	Método	Parâmetros
city-council/agenda	Agenda das sessões da Câmara de Vereadores	GET	query (buscará na descrição das agendas), start_date, end_date
city-council/attendance-list	Assiduidade dos vereadores	GET	query (buscará na nos nomes dos vereadores), start_date, end_date
gazettes	Diário Oficial (do executivo e do legislativo)	GET	power (legislativo ou executivo), start_date, end_date, query (buscará nos eventos, edição e ano)
bids	Licitações do poder executivo	GET	🚧 documentação em construção

As buscas textuais não fazem distinção entre maiúsculas e minúsculas.