Jan/2019 - Mudanças que podem causar problemas

[EquipeDadosAbertosCD]

Prezad@s usuári@s do Dados Abertos,

Algumas mudanças que serão implementadas em breve no serviço poderão afetar aplicações. Este anúncio é um aviso para que sejam providenciadas com alguma antecedência as modificações que se façam necessárias.

1 - Reorganização dos endpoints /referencias

Está previsto que em 29/01 (terça-feira) entre em operação a nova organização dos endpoints subordinados a /referencias, que já foi solicitada por alguns dos usuários do Dados Abertos. Os endpoints que já foram publicados até hoje, como /referencias/situacoesDeputado, continuarão operacionais por prazo indeterminado, mas poderão ser desativados em alguma atualização seguinte, e não mais serão mencionados na página Swagger que descreve a API (https://dadosabertos.camara.leg.br/swagger/api.html).

2 - Alterações de nomes de campos e parâmetros

Também a partir de 29/01 (terça-feira), alguns campos de dados e parâmetros de query string da API, bem como campos nos arquivos, terão seus nomes substituídos:

• /eventos:

  • Parâmetros:
    • idSituacao passa a ser codSituacao
    • idTipoOrgao vira codTipoOrgao
    • idTipoEvento passa a ser codTipoEvento
  • Campos:
    • idTipoOrgao passa a codTipoOrgao

• /proposicoes:

  • Parâmetros:
    • idAutor passa a ser idDeputadoAutor
    • 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}/orgaos, /legislaturas/{id}/mesa, /orgaos/{id}/membros:

  • Campos:
    • papel passa a ser titulo
    • idPapel passa a ser codTitulo

• /deputados/{id}/despesas:

  • Campos:
    • idDocumento vira codDocumento
    • idLote torna-se codLote
    • idTipoDocumento passa a ser codTipoDocumento

A razão dessas mudanças é óbvia mas até o momento passou despercebida pela equipe do Dados Abertos: "id" e "uri" são termos e sufixos usados nas referências a recursos da API. Parâmetros e campos como idSituacao ou idTipoDespesa não dizem respeito a recursos, mas sim a dados qualificadores de recursos. A nova implementação do endpoint /referencias já levará em consideração estes novos nomes.

3 - Limitação das requisições

Em algum momento entre 25/01 e 04/02, passará a haver limitação mais rigorosa do número de requisições por segundo permitidos a uma mesma aplicação cliente.

A principal finalidade da API é fornecer pequenas quantidades de dados, já selecionados previamente à requisição -- por exemplo, as informações sobre um deputado, ou a agenda de uma comissão durante a semana seguinte.

Sabemos que há vários usuários que usam a API para alimentar bases de dados locais, o que não é um problema em si -- mas pelos logs de acesso ao serviço percebemos que isso nem sempre é feito de forma, digamos, racional. Por exemplo, sequências de requisições por recursos inexistentes, com erro atrás de erro, indicam que há código fazendo loop com valores de {id} sem sequer verificar o sucesso de cada requisição.

Além disso, parece haver usuários que com muita frequência recarregam dados que não tiveram nem terão mais mudanças, como registros de despesas parlamentares com mais de dois anos, ou dados sobre proposições há muito tempo arquivadas e inativas.

A sobrecarga em determinados horários alertou a área de infraestrutura de internet da Câmara, que nos solicitou avaliar a limitação como a solução menos prejudicial ao coletivo de usuários e ao acesso a todos os dados.

Para os usuários que realmente precisam fazer grandes cargas de dados, recomendamos que sejam utilizados os arquivos de dados oferecidos na página https://dadosabertos.camara.leg.br/swagger/api.html#staticfile . Esses arquivos são atualizados diariamente e novos conjuntos de arquivos estão sendo desenvolvidos para fornecer os mesmos conjuntos de dados da API. Mas se os dados desejados só estiverem disponíveis na API, solicitamos que seja incluído um período de pausa entre as requisições e/ou a diminuição do número de acessos assíncronos simultâneos.

Atenciosamente,

Equipe de Dados Abertos - Câmara

[gacra]

@CeninCD, a API antiga terá alguma modificação também, ou o que foi escrito vale apenas para a nova?

[EquipeDadosAbertosCD]

Salve, @gacra !

A limitação do número de requisições vai ser aplicado às duas APIs. As demais modificações são restritas à nova.

Abraço e obrigado por perguntar!

Fabricio Rocha
Equipe Dados Abertos - Câmara

[caioflores]

Boa tarde @CeninCD, tudo bom? Sou Caio Flores CTO do sigalei, já conversamos algumas vezes por aqui e já fizemos contato algumas vezes pessoalmente ai no Laboratório.

Alguns métodos da API antiga já estão retornando 429, isso estava programado?
Vou entrar em contato com vocês na segunda de manhã por telefone para tirar algumas dúvidas sobre essas restrições, tudo bem?

Nós fazemos muitas requisições para a API mas tentamos sempre seguir boas práticas para não sobrecarregar os servidores. E a informação (e o timing) dessas informações é crítica para os nosso clientes, por isso gostaríamos de alinhar com vocês se estamos seguindo os padrões que vocês sugerem. Em caso negativo, gostaríamos de alinhar com vocês um plano de ação para adaptarmos nossa extração antes que seja realizado qualquer tipo de bloqueio.

Abraços.