Versão 0.2.26 da API - Release Notes

Às vésperas do início da legislatura 56 da Câmara dos Deputados, a atualização da API do Dados Abertos traz um monte de novidades e correções que nós esperamos que agradem aos nossos usuários.

Novo endpoint `partidos/{id}/membros`

O novo endpoint lista os deputados que são membros de um partido, mas não apenas no momento da requisição: também é possível usar parâmetros idLegislatura ou dataInicio e dataFim para obter uma lista de deputados que foram integrantes do partido {id} em um certo intervalo de tempo -- uma informação que não é disponível na antiga versão do Dados Abertos e nem mesmo no Portal da Câmara.

Classificação temática de proposições

Um usuário do Dados Abertos na própria Câmara, nosso 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". Logo vimos que a publicação desta classificação temática seria um prato cheio para aplicações interessantes do Dados Abertos.

Proposições podem ser classificadas com mais de uma área temática, e para evitarmos um aninhamento de dados -- difícil de reproduzir nos arquivos de planilha dos Dados Abertos -- foi criado o endpoint /proposicoes/{id}/temas, que fornece a lista dos temas que a proposição {id} abrange. Além disso, foi criado o parâmetro de busca codTema para o endpoint /proposicoes, que recebe um ou mais dos valores fornecidos pela lista em /referencias/proposicoes/codTema.

Os `id` que viraram `cod`

Como anunciado em 24/01/2019, 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
/proposicoes:
- Parâmetros:
  - idSituacao passa a ser codSituacao
/proposicoes, /proposicoes/{id}/relacionadas:
- Campos:
  - idTipo passa a codTipo
/proposicoes/{id}/tramitacoes:
- Campos:
  - idTipoTramitacao torna-se codTipoTramitacao
  - idSituacao passa a codSituacao
/orgaos e /orgaos/{id}:
- Parâmetros:
  - idTipoOrgao passa a ser codTipoOrgao
- Campos:
  - idTipoOrgao passa a ser codTipoOrgao
/deputados/{id}/despesas:
- Campos:
  - idDocumento vira codDocumento
  - idLote torna-se codLote
  - idTipoDocumento passa a ser codTipoDocumento

`/proposicoes` com alterações

O parâmetro idAutor do endpoint /proposicoes foi substituído por idDeputadoAutor por uma outra razão. 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âmetros para permitir a busca por diferentes tipos de autores.

Outra novidade no endpoint está debaixo do capô: a consulta ao banco de dados passou por otimizações para tornar as respostas mais rápidas.

Tramitações de uma proposição em intervalo de tempo

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

"papel" substituído por "título"

Nos dados retornados pelos endpoints /deputados/{id}/orgaos, /legislaturas/{id}/mesa e /orgaos/{id}/membros, o campo papel passa a se chamar titulo e o campo idPapel passa a ser codTitulo.

Mudanças em `/referencias`

Todo o conjunto de dados /referencias foi reorganizado para, como bem definiu o usuário Hugo Benício em 03/10/2018 (https://github.com/labhackercd/dados-abertos/issues/188), 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 qualificação de dados, como 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, os antigos endpoints ´/referencias/tiposEvento´ e /referencias/situacoesEvento, por exemplo, passam a ser /referencias/eventos/codTipoEvento e /referencias/eventos/codSituacaoEvento. Ou seja: o segundo elemento do path passa a ter o nome do conjunto de dados no qual os nomes usados na terceira posição do path são campos ou parâmetros. Isto é: em geral, abaixo de /referencias se segue o nome de um endpoint principal e o nome de algum parâmetro que recebe um ou mais valor(es) da lista fornecida. Embora a explicação possa parecer muito enrolada, uma olhada na página de documentação da API mostra que a lógica fica mais clara e automatizável.

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, /referencias/proposicoes passa a ter, como retorno, as listas fornecidas por /referencias/proposicoes/siglaTipo, /referencias/proposicoes/siglaTipo, /referencias/proposicoes/codSituacaoe/referencias/proposicoes/codTema`.

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

Correção em `/orgaos/{id}/membros`

Incorretamente, o endpoint estava listando, por padrão, todos os deputados que já foram membros do órgão {id}. Com a correção, passam a ser retornados os parlamentares que são integrantes do órgão no momento da requisição.

Novo endpoint: `/eventos/{id}/orgaos`

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 é problemática para os formatos de planilha nos quais os arquivos do Dados Abertos são fornecidos. O novo subrecurso permitirá que, futuramente, a lista possa ser desmembrada do retorno de /eventos/{id}.

Parâmetros desconhecidos geram 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 seus relatos de bugs e sugestões, muito obrigado e mantenham contato!

Fabricio Rocha Equipe Dados Abertos - Câmara

CamaraDosDeputados / dados-abertos