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.
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 ?).
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.
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).
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
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.