-
Notifications
You must be signed in to change notification settings - Fork 44
Bugs na API da Câmara dos Deputados
Criado em 17/02/2016 pelo LabHacker da própria Câmara: https://github.com/labhackercd/dados-abertos/issues
Os endpoints estão confusos tanto nos nomes quanto nos sub-items. Ex:
- ObterDeputados, ListarProposicoes (os dois fazem a mesma acão, mas com verbos diferentes)
- Dentro de Orgaos temos: ObterEmendasSubstitutivoRedacaoFinal. Esta é apenas um exemplo, mas acredito que deveria estar em "Proposicoes".
É uma boa prática utilizar-se do modelo REST[1]. Ela usa 4 métodos para representar as ações: GET, POST, PUT and DELETE. Então neste caso, o usuario pode fazer GET em um endpoint de lista, ou endpoint específico:
# Retornaria a lista de deputados;
GET http://api.example.com/v1/deputados/
# Retornaria os detalhes do deputado 1.
GET http://api.example.com/v1/deputados/1/
Outro exemplo é ObterProposicaoPorID que poderia ser:
GET http://api.example.com/v1/proposicoes/23232/
Algumas estruturas são exibidas diferentes dependendo se é endpoint de lista ou de detalhe.
Exemplos:
- Na lista de deputados (ObterDeputados), gabinete, anexo e fone são itens separados. Já nos detalhes do deputado (ObterDetalhesDeputado), estão dentro da estrutura "gabinete".
Sempre que possível, as referências devem ser amarradas por campo de chave identificadora.
Exemplos:
- ObterDeputados, lista comissoes, mas não mostra o id da comissao.
- ObterLideresBancadas, cada lider e vice lider não possui o ide_parlamentar.
Durante varias consultas alguns códigos de "orgao" não estão na lista de orgaos (ObterOrgaos).
Exemplos:
- idOrgao = 4 (MESA - Mesa Diretora da Câmara dos Deputados)
- idOrgao = 180 (Plenário)
Para listar proposicoes por exemplo (ListarProposicoes) a documentação fala que varios campos são opcionais na consulta. Mas infelizmente para realizar a consulta temos que passar todos os campos, mesmo que em branco.
A lista de mandatos (exercícios) do parlamentar não está completa. Apenas mostra os últimos exercícios.
Encontrei 250 votações em proposições com deputados sem ideCadastro. Por exemplo, em http://www.camara.gov.br/SitCamaraWS/Proposicoes.asmx/ObterVotacaoProposicao?tipo=MPV&numero=198&ano=2004:
<Deputado Nome="Hamilton Casara" ideCadastro="" Partido="PSB " UF="RO" Voto="Não "/>Seguindo o padrão REST e HTTP, ele deveria retornar 200 para uma requisição com sucesso (como esta), e 404 caso não encontrada (como esta).
Versionamento é importante para não quebrar futuros códigos. A API não possui em seus endpoints a versão da API. É uma boa prática utilizar endpoints com versão explicita.
Exemplo:
http://api.example.com/v1/things/foo/
Outra boa prática, inclusive para ajudar em rápidas requisições, é possuir um cabeçalho de paginação. Listas grandes podem demorar muito e congestionar o servidor.
Exemplo (em .json, mas poderia ser xml):
"meta": {
"limit": 500,
"next": /api/v1/proposicoes/,
"offset": 0,
"previous": null,
"total_count": 4000
},
No exemplo acima, o desenvolvedor por fazer a listagem de todas mas apenas 500 são retornadas por vez.
Cada votação poderia ter um ID único que a identificasse, isso facilitaria o trabalho de referenciar as votações em si. Hoje não há um campo essencialmente diferenciador entre duas votações de uma mesma proposição que "ocorram" (ou sejam registradas) num mesmo dia/horário.