Página Notícia

Logo antes do início da legislatura 56 da Câmara dos Deputados, a equipe do Dados Abertos publicou uma atualização da nova API e do sistema de geração de arquivos para download, com a correção de vários bugs e a implementação de alterações e novos conjuntos de dados há muito tempo aguardados. Mudanças no próprio ciclo de desenvolvimento devem ser feitas a partir desta versão – aliás, este é um dos motivos do salto na numeração de revisão entre as versões.

Deputados de um partido... ao longo do tempo

Foi implementado na API o endpoint /partidos/{id}/membros, que, sem parâmetros, lista os deputados que são membros de um partido no momento da requisição. Mas também é possível usar os parâmetros idLegislatura ou dataInicio e dataFim para obter uma lista de deputados do partido {id} no intervalo de tempo desejado. É a primeira vez que esta informação se torna disponível nos serviços da Câmara na internet, e é um passo inicial para a implementação de outros recursos "de histórico" previstos pela especificação, como /deputados/{id}/historico.

Áreas temáticas das proposições

Um usuário do Dados Abertos na própria Câmara, o colega Francisco Cardozo, chamou nossa atenção, em dezembro, para a existência de dados de classificação das proposições por áreas temáticas, tais como "Direito Civil e Processual Civil" ou "Arte, Cultura e Religião". Já vínhamos publicando os dados de proposições com um campo keywords, com as palavras-chave usadas para indexação das proposições, e soubemos que alguns usuários já as utilizam para fazer seus próprios esquemas de agrupamento temático. Os novos dados, porém, permitem que esse agrupamento seja feito com a classificação definida pelo Centro de Documentação e Informação da Câmara, sob as regras do thesaurus oficial da casa.

Foi criado um novo conjunto de arquivos para download, proposicoesTemas-{ano}.*, para ligar os identificadores de proposições aos identificadores de áreas temáticas. Proposições podem ser classificadas com mais de uma área temática, e nos formatos de arquivo para planilhas isso exige que haja mais de um registro (linha) por proposição. Como temos tentado manter as respostas da API parecidas com as dos arquivos, optamos por criar nela um novo endpoint, /proposicoes/{id}/temas, em vez de incorporar a lista de temas ao retorno de /proposicoes/{id}. Também na API foi criado o parâmetro de busca codTema para o endpoint /proposicoes, que recebe um ou mais dos identificadores numéricos das áreas temáticas. Esses identificadores podem ser obtidos no endpoint /referencias/proposicoes/codTema. Aliás...

Proposições: outras (várias) mudanças

Os endpoints de proposições passaram por várias alterações desde a última atualização. Uma delas não exige adaptações dos usuários, mas esperamos que seu efeito seja bem sentido: foram otimizadas as consultas às bases de dados, e um ganho de desempenho deverá ser sentido, principalmente, nas buscas em /proposicoes que são feitas com os mesmos critérios por diferentes usuários.

O parâmetro idAutor do endpoint /proposicoes foi substituído por idDeputadoAutor. Por enquanto só é possível selecionar proposições que sejam de autoria de um ou mais deputados, para os quais a API tem identificadores exclusivos; mas proposições também podem ser apresentadas por senadores, por outros poderes da República, por Assembleias Legislativas estaduais e por cidadãos. Em alguma das próximas atualizações, será implementado um parâmetro para permitir a busca por diferentes tipos de autores.

O endpoint /proposicoes/{id}/tramitacoes passa a suportar os parâmetros dataInicio e dataFim – outra sugestão do nosso colega Francisco Cardozo.

Órgãos realizadores de um evento

Eventos como audiências públicas podem ser realizados por mais de um órgão. Atualmente a lista de órgãos responsáveis por um evento é incorporada a /eventos/{id}, mas esta lista aninhada, tão trivial para formatos hierárquicos como JSON e XML, é problemática para os formatos de planilha nos quais os arquivos do Dados Abertos também são fornecidos. O novo subrecurso /eventos/{id}/orgaos permitirá que, em uma atualização futura, a lista possa ser desmembrada do retorno de /eventos/{id}. Recomendamos aos nossos usuários que já passem a utilizar o novo endpoint em suas aplicações.

Nova organização nos endpoints /referencias

Todo o conjunto de dados /referencias foi reorganizado para, como bem definiu o usuário Hugo Benício no nosso fórum no GitHub em 03/10/2018, torná-lo "mais RESTful", e mais coerente com a organização adotada em toda a API.

O papel do endpoint /referencias é fornecer listas de valores usados para busca ou qualificação de dados, como as situações de exercício de um deputado, os tipos de proposições e os tipos de eventos. Esses valores são usados principalmente em parâmetros de filtragem e seleção em diversos endpoints que retornam listas, como /deputados e /eventos.

Na nova organização, o segundo elemento do path passa a ser o nome de um dos conjuntos de dados da API, e o terceiro elemento do path passa a ser o nome de um parâmetro ou campo usado neste conjunto de dados. Por exemplo: os antigos endpoints /referencias/tiposEvento e /referencias/situacoesEvento passam a ser /referencias/eventos/codTipoEvento e /referencias/eventos/codSituacaoEvento. Em outras palavras: em geral, abaixo de /referencias se segue o nome de um dos endpoints principais da API, e em seguida o nome de algum parâmetro que exige valores específicos; e a resposta é uma lista com esses valores. A explicação é mesmo enrolada, mas uma olhada na página de documentação da API mostra que os endereços do endpoint ficaram mais claros e até automatizáveis.

Além disso, já nos endpoints de dois níveis passam a ser retornadas todas as listas que também são fornecidas individualmente como subrecursos. Por exemplo, basta uma chamada a /referencias/proposicoes para que se obtenha como retorno as listas também fornecidas por /referencias/proposicoes/siglaTipo, /referencias/proposicoes/siglaTipo, /referencias/proposicoes/codSituacao e /referencias/proposicoes/codTema.

Os antigos endpoints continuam funcionando temporariamente, e os novos endpoints já incorporam os novos nomes "cod*" dos parâmetros e campos.

Renomeação de campos e parâmetros "id*" para "cod*"

Foi revista a nomenclatura de campos e parâmetros de query string em vários endpoints da API, e a revisão está sendo aplicada também aos arquivos do Dados Abertos. Alguns campos e parâmetros eram usados para designar valores qualificadores de dados, mas vinham usando o prefixo "id", que é usado para identificadores de recursos na API. Estes campos foram renomeados para usar o prefixo "cod": por exemplo, o parâmetro idTipoOrgao que era usado para filtrar os resultados de /eventos e /orgaos passa a se chamar codTipoOrgao.

• /eventos
  • Parâmetros
    • idSituacao passa a ser codSituacao
    • idTipoOrgao vira codTipoOrgao
    • idTipoEvento passa a ser codTipoEvento
  • Campos
    • idTipoOrgao passa a codTipoOrgao
• /orgaos e /orgaos/{id}
  • Parâmetros
    • idTipoOrgao passa a ser codTipoOrgao
  • Campos
    • idTipoOrgao passa a ser codTipoOrgao
• /orgaos/{id}/membros, /legislaturas/{id}/mesa e /deputados/{id}/orgaos
  • Campos
    • idPapel passa a ser codTitulo
    • papel passa a ser titulo
• /proposicoes
  • Parâmetros
    • idSituacao passa a ser codSituacao
• /proposicoes e /proposicoes/{id}/relacionadas
  • Campos
    • idTipo passa a codTipo
• /proposicoes/{id}/tramitacoes
  • Campos
    • idTipoTramitacao torna-se codTipoTramitacao
    • idSituacao passa a codSituacao
• /deputados/{id}/despesas
  • Campos
    • idDocumento vira codDocumento
    • idLote torna-se codLote
    • idTipoDocumento passa a ser codTipoDocumento

Parâmetros desconhecidos passam a resultar em erro

Devido ao comportamento padrão da plataforma usada para a API, parâmetros de query string que não eram suportados vinham sendo silenciosamente ignorados. Isso costumava causar surpresas desagradáveis: uma busca em /eventos com os parâmetros dataHoraInicio e dataHoraFim, por exemplo, não sairia como o imaginado, porque neste endpoint os parâmetros de data e horário são separados.

Para evitar problemas assim, o comportamento foi reconfigurado para que seja retornado um erro 400 se houver na query string um parâmetro desconhecido.

A todos que colaboraram para esta atualização com suas sugestões, críticas e relatos de problemas, muito obrigado e mantenham contato!

Ir para lista de Notícias