[PROPOSTA] Adição de parâmetro role para filtragem na operação de listClaims

[luizlaydner]

Motivação: Os filtros isDonor, isClaimer da operação de listClaims não tem comportamento muito claro para algumas combinações de valores. Além disso, a especificação não deixa bem definido se esses filtros se combinam como conjunção (AND) ou como disjunção (OR). Por fim, há ainda que se considerar o comportamento quando o valor de um desses parâmetros não é passado. Essa complexidade toda deixa a API menos intuitiva e mais propensa a erros de implementação.

Proposta: Adicionar um parâmetro role, que poderia assumir os valores DONOR ou CLAIMER, na filtragem de listClaims. Para manter a compatibilidade da API, os parâmetros isDonor e isClaimer continuariam a existir e teriam sua definição com base em uma equivalência ao parâmetro role. Algumas combinações "estranhas" (não utilizadas na prática) passariam a ser inválidas.

A tabela abaixo resume o comportamento atual da API e o comportamento com a nova definição.

isDonor	IsClaimer	Comportamento atual	Nova definição em termos de "role"
True	True	Retorna claims em que participante é doador OU reivindicador	Inválido
True		Retorna claims em que participante é doador	role=DONOR
True	False	Retorna claims em que participante é doador	role=DONOR
False	True	Retorna claims em que participante é reivindicador	role=CLAIMER
False		Retorna claims em que participante é reivindicador	role=CLAIMER
False	False	Retorna claims em que participante é doador OU reivindicador	Inválido!
	True	Retorna claims em que participante é reivindicador	role=CLAIMER
	False	Retorna claims em que participante é reivindicador (bug!)	role=DONOR
		Retorna claims em que participante é doador OU reivindicador	role=

Perguntas:

• Essa evolução da API a deixaria mais intuitiva ?
• Uma futura remoção dos parâmetros isDonor e isClaimer, com a substituição pelo parâmetro role, teria impacto muito grande de implementação no seu participante?

Proposta complementar: Tornar o parâmetro role obrigatório.

A fim de simplificar o desenho do backend do DICT, melhorar o desempenho da query e diminuir o consumo de recursos no SGBD, estamos considerando a alternativa de tornar o parâmetro role obrigatório.

Perguntas:

Tornar esse parâmetro obrigatório teria impacto de implementação muito grande no seu participante ?

[gabrielmendesbb]

Acho a ideia boa, porem, eu particularmente, acho que alterações no protocolo gera muito esforço devido a estrutura da organização, principalmente nesse caso de tornar o campo obrigatório. Sugiro manter como está, só corrigindo o BUG e esclarecendo melhor o funcionamento na documentação do DICT API.

[judahreis]

@gabrielmendesbb, a mudança é necessária pois a pesquisa como doador e reivindicador simultaneamente gera uma sobrecarga do banco de dados que, com o tempo, pode prejudicar a performance. A ideia é separar a pesquisa desses dois papeis.

[mvleandro]

Caros,

Não vejo benefício real na proposta sugerida.

Atualmente os parâmetros de IsDonor e IsClaimer atendem a todos os cenários possíveis.

Minha única recomendação é deixar a documentação da api mais clara quanto ao comportamento da combinação destes parâmetros.

Meu voto é para que não haja alteração na api neste sentido.

[gabrielmendesbb]

@judahreis Entendo a necessidade da mudança internamente, porem vc consegue fazer esse ajuste sem alterar o protocolo de entrada. So vc fazer um "de para" dentro do seu sistema. Ratifico que qualquer mudança nos protocolos da API geram muito impacto na alteração do sistema, devido a estrutura tecnológica interna da organização. Acho q mudanças no protocolo só devem ser feitas se realmente necessárias. E na minha opinião esse não é o caso. Sem falar q essa mudança não é retro compatível com a versão atual.

[rafaelmsousa]

@judahreis De fato, a alteração proposta tornaria um pouco mais claro o funcionamento desse(s) filtro(s) - isDonor e isClaimer. Porém não acho que seja um momento oportuno, faltando menos de 2 semanas para o lançamento do produto. Sugestão manter retrocompatibilidade, sem criar um campo novo, mantendo os campos atuais como opcionais, somente definindo valores padrão para os filtros e acrescentando algumas validações no backend do DICT-BACEN. Exemplo:

Nome do Filtro - Obrigatório/Opcional - Valor Padrão

isDonor - opcional - true isClaimer - opcional - false

Deixar claro na documentação da API que não é possível utilizar as combinações citadas como inválidas - Ex: isDonor=False, isClaimer=false, e implementar validações com mensagens de retorno ou códigos de erro específicos para esse tipo de validação no swagger.

[marinafsiq]

Se for um campo opcional e não obrigatório pode ajudar outros players, mas inicialmente não o Nubank devido a implementação que fizemos. Se for obrigatório seria uma mudança que impactaria pois os times teriam que mudar as APIs, e o PIX é um projeto novo que precisamos dedicar tempo para on-call e bugs que podem aparecer, ficar mudando API requer sempre um trabalho extra de mudança de código e testes.

[fCamargosRibeiro]

Acho que a proposta é boa e valida, o impacto existe, mas acho que visto a melhoria que ele trás é importante. Mas acredito que para isso funcionar bem é importante ele vir junto com a paginação. Pois é interessante fazer menos consulta para gente também nesse processo do polling, mas hoje só com o HasMoreElements acaba que temos que fazer mais pollings para garantir que o limit de 200 não seja ultrapassado.