Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?

Objetivo

O objetivo principal é que ao invés de que sejam feito Forks do código para cada cidade construir sua API, a Gastos Abertos se torne um repositório referencial de dados do Orçamento Público Municipal.

Neste caso, em parcerias com outras cidades poderia-se negociar que os dados fossem fornecidos ou parte do código estendido e feito um pull-request para incorporar ao código do projeto.

A ideia aqui é portanto de documentar quais partes do código seria necessário o entendimento e a extensão para realizar o pull-request, ao invés de esperar que novas cidades precisem entender tudo.

O trade-off entre ter que entender tudo e mover toda a estrutura para um outro local, versus apenas modificar poucas partes para manter os dados centralizados seria a maior motivação para a Gastos continuar a agregar dados ao invés de ter o projeto distribuído por todos os cantos, o que dificultaria encontra-los ou correria o risco de não serem mantidos a longo-prazo.

Assim sendo, este card tem como objetivo o mínimo de documentação necessário para extender o código.

Detalhes do Processo de Decisão da API

Existe alguns documentos sobre isso no Github documents da Open Knowledge.

Atualmente os endpoints estão destacando operações de:

  • Listagem dos dados.
  • Filtragem dos dados.
  • Agrupamento dos dados.

Além disso somente o formato JSON é disponibilizado, o que limita qualquer possibilidade de utilização por parte dos jornalistas (TO-DO output=csv ?).

Fontes e Pre-Processamento dos dados listados em Python Notebooks.

Armazenamento de Dados Pre-Processados

Os dados são armazenados em um RDBMS (Postgres ou MySQL) e possui 4 tabelas.

  • Contratos
  • Execução
  • Receita
  • Códigos da Receita

Os arquivos model.py nos repositórios de Receita, Execução e Contratos contem o schema da tabela.

Para acesso aos dados do Banco, usamos SQL Alchemy.

API e Acesso aos Dados do Banco

A API é construida usando Flask (mesmo usado para o Website), um framework leve para construção de websites (parecido com Django mas muito mais modular em só usar o que quer de funcionalidade).

Uma dessas extensões do Flask é a REST Plus, que "implementa" a API.

Para prover uma documentação mínima da API gerada automaticamente a partir do código, usamos sub-funções do REST Plus com o Swagger.

Os arquivos views.py nos repositórios de Receita, Execução e Contratos implementam o código da API bem como a documentação exibida no Swagger quando abrimos o site da API (e.g. a descrição de cada campo pode ser editada aqui).


Criar um Endpoint

A class ContratoListApi é o melhor exemplo pois tem a doc logo acima. Criar uma classe e definir os seguinte decorators:

  • @ns.route define o URL
  • @api.doc a documentação swagger
  • @api.marshall como a resposta será montada
@ghost

This comment has been minimized.

Copy link

commented Dec 15, 2015

Isso aqui não está terminado e o texto é todo meu de um card do Trello. Cria um issue para isso e me da assignment por favor.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.