lafaiet / salicapi Goto Github PK

Notei que não há na documentação, lugar algum indicando qual a ordenação padrão pela qual os itens são apresentados em uma consulta caso a query 'sort' não tenha sido passada. Para projetos, por exemplo, creio que é PRONAC, não tenho certeza... seria com estar lá da mesma maneira que 'offset' e 'limit' já estão.

A API deve disponibilizar apenas os projetos do Mecanismo "Mecenato". Para isso é necessário implementar um filtro padrão na tabela Projetos filtrando o parâmetro Mecanismo com o valor 1.

Este registro, por exemplo, não está ok: http://hmg.app.api.salic.cultura.gov.br/#/projetos/123667

Este requisito foi levantado durante a homologação com a área responsável. Os Projetos que utilizam os demais Mecanismos requerem outras estruturas de informação na API. Isto fica como requisito futuro de evolução.

Parece que a consulta /fornecedores/{id}/ está retornando Status 504:

{
"message": "internal error",
"message_code": 17,
"more": "something is broken"
}

Para reproduzir o erro: Acessar qualquer consulta ao fornecedor, por exemplo essa.

Ressalto que consultas /fornecedores/ e /fornecedores/{id}/produtos/ estão funcionando corretamente.

• Colocar cabeçalho de arquivo CSV, assim o navegador sabe o que é e pode sugerir abrir numa planilha

• Colocar um nome amigável para o arquivo, com a extensao .csv

Sugestões de nomes. (acho que podemos discutir aqui um pouco:

prefixo - acho que todos os arquivos poderiam começar com versalic- ou só salic-

entidade - em seguida poderia vir o nome da entidade exportada: projetos, fornecedores, etc.

Por último poderia vir alguma coisa que identificasse aquela consulta... Ainda mais quando tiver que fazer vários downloads para uma consulta com mais de 100 itens, os arquivos tem q ter nome diferente, se não vai ser ruim.

Propostas

1. Montar um hash md5 jogando todos os parametros da busca, incluindo offset e limit. Isso é legal pq daí dá pra guardar num cache esse csv se quiser.

2. colocar só o offset e limit

Exemplo na opção 1:

versalic-projetos-202cb962ac59075b964b07152d234b70.csv

ou com um hash resumido

versalic-projetos-d234b70.csv

Na opção 2

versalic-projetos-1-100.csv

Ou ainda podemos combinar as duas coisas. O offset no nome do arquivo é bom para o usuário:

versalic-projetos-1-100-d234b70.csv

• Incluir na entidade Projeto um link para a Proposta relativa
• Incluir na entidade Proposta link para o Projeto, caso haja

Na construção dos links para download de arquivos anexos, não usar o endereço com novosalic.cultura.gov.br, e sim salic.cultura.gov.br

Não funciona: http://novosalic.cultura.gov.br/verprojetos/abrir-documentos-anexados?id=170523&tipo=2&idPronac=208183

Funciona: http://salic.cultura.gov.br/verprojetos/abrir-documentos-anexados?id=170523&tipo=2&idPronac=208183

Os campos Resumo, Etapa, Objetivos, Sinopse, etc. são armazenados em formato HTML no banco de dados. Atualmente a API remove por padrão a formatação destes textos e expõe um texto plano.

Com o objetivo de possibilitar maior flexibilidade na manipulação destes campos é preciso fornecer a opção de acesso ao formato HTML. Para isso podemos dispor um parâmetro (textoRico) que pode ser setado para true o que desligaria o filtro padrão.

Nas consultas por projeto, há um vetor que está sendo retornado, mas não está na documentação: "relacao_bens_capital". Eu demorei um bocado pra achar um exemplo de projeto que tivesse esse campo, mas hoje consegui um:
http://hmg.api.salic.cultura.gov.br/beta/projetos/138997/

Já implementei no VERSALIC. Porém, observando os campos, parece que eles fogem do padrão utilizado para os nomes de atributos até então (letras minúsculas, separação por underline), estão com camel case... enfim, acho que deve ter deixado passar essa. Quando puder corrigir por favor me notifique para que eu altere no site também e evite de quebrar as páginas de projeto.

Não tenho certeza se isso poderia ser um erro de implementação ou se é só a lógica por trás que é mais custosa mesmo... mas fazendo alguns testes, parece que a consulta por Proponentes, quando ordenada por 'total_captado' é muito mais demorada que as demais.

Por exemplo:
http://hmg.api.salic.cultura.gov.br/beta/proponentes/?limit=100&offset=0&sort=total_captado == 734ms
http://hmg.api.salic.cultura.gov.br/beta/proponentes/?limit=100&offset=0&sort=total_captado == 18s!!

Isso é normal?

É complicado não termos como alterar entre crescente e descrescente nos campos padrão de ordenação de algumas entidades. 'cgccpf', por exemplo, na consulta por Proponentes e Incentivadores, é a ordenação padrão mas não está disponível na API, apenas os métodos alternativos, 'total_captado' e 'total_doado' respectivamente.

Entendo que o valor semântico de cgccpf possa não ser interessante nesse sentido, mas acho que precisamos de um padrão. Projetos expõe por completo seu método padrão (PRONAC). Proponente e Incentivadores possuem métodos alternativos de ordenação, mas não expõe seu padrão. Propostas e Fornecedores não possuem alternativas... :/

Acho que a solução mais simples para isso é termos #11 aplicada. Mas enquanto não for possível, expor 'cgccpf' resolveria meus dilemas....

Foi conversado um tempo atrás sobre a necessidade de termos campos do tipo 'data_inicio_min', 'data_inicio_max', 'data_termino_min' e 'data_termino_max' na consulta por Propostas. Atualmente os parâmetros de data exigem uma data exata, o que é muito específico para uma consulta exclusiva.

Sendo um campo comum à todas as entidades e semanticamente coeso, acredito que deveria ser possível a ordenação por nome em todas as entidades. Provavelmente isso pode servir de ordem padrão em alguns casos.

• por Incentivador
  Permitir filtrar todos os projetos onde pelo menos um incentivo foi fornecido por um Incentivador específico. A relação entre Projeto e Incentivador é indireta e através de uma entidade MN

• por Fornecedor
  Permitir filtra todos os projetos onde pelo menos serviço/produto foi fornecido por um Fornecedor específico. A relação entre Projeto e Fornecedor é indireta e através de uma entidade MN

• por Valor do Projeto e valor Captado
  Assim como feito para os campos de data, é preciso permitir filtragem por range dos campos de valores uma vez que o valor específico é uma informação pouco útil

• por Situação
  Similarmente como para segmento, incluir filtro por Situação do Projeto. Também é necessário disponibilizar método que lista os tipos de Situações

Listas de objetos na consulta projetos/PRONAC devem ser inseridas dentro do respectivo embedded , seguindo o padrão HAL.

Algumas consultas por Doações com offset alto estão demorando muito e resultando em timeout. Exemplos com os dois Incentivadores que mais doaram:

• Doações da Vale, limit = 100, offset = 500 ;

• Doações da Petrobrás, limit = 12, offset = 10692 ;

No link http://dados.cultura.gov.br/dataset/incentivos-da-lei-rouanet não faz o download da bse toda, apenas dos primeiros 100.
Alguem ajuda?

De maneira similar ao caso dos Incentivadores no vetor doacoes, poderíamos ter um link para o Fornecedor em cada item do vetor relacoes_pagamentos na consulta ao Projeto.

Isso aumentaria as possibilidades de navegação, já que no momento temos os dados do Fornecedor, mas precisamos fazer a consulta filtrada pelo CGCCPF ou nome do mesmo para chegar até sua página.

Há alguns campos no Model Scheme de Projeto que estão sem descrição de conteúdo. Podemos inferir o que há neles pelo resultado da consulta, mas nem sempre estes vem com valores dentro. Os que eu notei até o momento:

• relatorio_fisico;
• relacao_pagamentos;
• readequacoes.pedidos;
• readequacoes.pareceres;

Apesar de já ser possível baixarmos os dados em JSON, XML e CSV, a escolha deste formato é passada pelo header da requisição, o que restringe as possibilidades de acesso à operações em backend. Se um cliente deseja fazer uma consulta via CSV, por exemplo, ele não tem como pedir somente via URL.

Como já foi discutido, isso é uma questão de padrão de projeto para a API, mas considero pertinente termos uma query do tipo "format" para fazer essa requisição de modo mais acessível ao usuário, facilitando o compartilhamento de dados consultados em outros formatos além do padrão.

Já foi comentado antes, mas só para deixarmos registrado...
Alguns projetos são listados na página de consulta, mas quando acessamos a consulta do Projeto em si, é retornado Erro 502 Bad Gateway.

Por exemplo: http://hmg.api.salic.cultura.gov.br/beta/projetos/123394/

Imagino que da mesma maneira como temos a relação Proponente <--> Projetos, deveríamos ter Proponentes <--> Propostas expostas pela API.

Exemplo: http://hmg.api.salic.cultura.gov.br/beta/fornecedores/?PRONAC=095056

Não sei se é contra o padrão que está sendo seguido, mas acredito que as consultas /fornecedores/{id}/produtos e /incentivadores/{id}/doacoes também deveriam permitir o uso de queries 'offset' e 'limit', além de retornar campos 'count' e 'total' da mesma forma que é feito nos recursos tipo listagem. Só a consulta de doações pelo Banco do Brasil por exemplo, já nos retorna mais de 100 itens!

Aparentemente a ordenação por valor_proposta na consulta pro Projetos não está funcionando (retorna Internal Error, Code 13, Something is broken, após alguns segundos de processamento.

Ex.: hmg.api.salic.cultura.gov.br/beta/projetos/?limit=10&offset=0&sort=valor_proposta:desc