Como melhorar a documentação da interface entre servidores e o Front-End?

[VitorLuizC]

@cristofersousa: Por gentileza, uma dúvida, no caso estou em um time da qual ainda não rola documentação da API. Pensando no crescimento do time, vejo a necessidade de fazer isso, mas é um cenário que o Back-end ainda não está lidando muito bem com o mesmo, no caso os microservices são criados com Node e estão com problemas no swagger pelo que tudo indica.

Dessa forma acabei meio que colocando nas issues quais os parametros esperados e quais parametros devem ser enviado e o endpoint do mesmo, pensando que esse histórico está em issue pode ser que no futuro se perca.

Sabendo disso, gostaria de documentar isso de uma forma de ficar mais exposto para o time de desenvolvimento no caso mais o FE. Pensei em adotar o JSDocs mas acho queria saber se alguém está passando por essa dor?

@CesarBMartinez: utilizamos o http://apidocjs.com/ para documentar nossa API Rest

@VitorLuizC: Vou ser bem sincero contigo, JSDoc não vai resolver o problema

@VitorLuizC: Faz um BFF ou algo semelhante e usa uma interface melhor pra entregar os dados da API. Minha sugestão é GraphQL, que é super bacana como orquestrador e você consegue usar pra documentar todos os grafos, ações etc da API

@VitorLuizC: Inclusive no Front-End você tem intellisense quando tá escrevendo uma query/mutation pra ele

@eltonea: @vitorluizc uma duvida que sempre tive, numa perspectiva de arquitetura da solução, porque usar microserviços para depois ter um BFF consolidando tudo pro meu front-end? Cada canal (mobile, web etc) deverá ter um BFF? Me parece que é ter mais trabalho pelo menos resultado.

@VitorLuizC: Vou responder por partes:

1. Não sei de você é familiarizado com o conceito de API Gateway, mas basicamente você tem um microsserviço que faz a gestão de permissões, consumo e centralização dos outros microsserviços da sua aplicação. Eu costumo comparar bastante o GraphQL com esse cara e acho que os dois servem de orquestradores para as outras aplicações que não tem que entender a abstração e regras de negócio usadas pra consumir os esses serviços.

2. É um erro levar as lógicas de consumo dos microsserviços para as aplicações da ponta que interage com o usuário, tanto por escala e manutenabilidade, quanto por segurança. GraphQL e API Gateways podem implementar regras de permissões e segurança, padronização de consumo dos dados, versionamento (com depreciação de APIs/Grafos).

3. BFF, GraphQL ou API Gateway é só mais um microsserviço, mas ele faz tudo o que falei acima e o ideal é ter um único para ser consumido nas aplicações que interagem com o usuário (web, mobile, bots etc).

@VitorLuizC: Eu concordo que dá trabalho, mas é um resultado que compensa bastante!

Nota: A discussão rolou no Slack do Vue.js Brasil e embora não tenha a ver com Vue.js é interessante ter esse histórico e até continuar o debate sobre o assunto.

Eu tomei liberdade de usar um título mais abrangente porque os casos são muito diferentes e as soluções tendem a ser também.

• Link da pergunta e discussão original no Slack.

Screenshot da discussão original no Slack

[eltonea]

@VitorLuizC, você concorda que uma API que utiliza BFF, somente faz sentido para:

• Manter contratos entre canais (web, mobile, desktop etc).
• Facilitar o desenvolvimento e seguir padrões de implementações (ex: Ember que utiliza contratos).
• Se o contexto do micro serviço é consistente e longo (pois, cada canal pode tirar proveito de óticas diferentes/modelagem 3D).

Resumidamente, na maioria dos cenários, sou contra o uso do BFF, pois creio que de pra escalar endpoints parecidos numa mesma aplicação, aproveitando a regra de negócio de tudo que já está construído (auth, infra, data etc), e manter uma aplicação consistente que representa, de forma fidedigna o negócio do cliente.

[kavalcante]

Cara, aqui a gente tentou Swagger e etc... A única coisa que funcionou e muito bem, foi quando colocamos GraphQL na aplicação. Dessa maneira, a documentação é gerada automaticamente e ainda existe um playground pro front chamar antes de implementar.

Não sei se ajudei, mas aqui realmente salvou e foi a melhor coisa que colocamos a uns 2 anos atrás.

[VitorLuizC]

@eltonea confesso que não manjo algumas coisas do que você escreveu?

• O que é um contrato?
• O que é um microsserviço consistente e longo?
• Quando você fala de escalar endpoints parecidos o que você quer dizer?

Quando eu penso em BFF, me vem a mente uma centralização de miscrosserviços e a implementação de algumas regras de negócio e persistência das aplicações de interface (web, mobile, bots etc). Eu tenho um case super recente de uma Lambda Function + GraphQL que o @cardosomarcos implementou e resolveu vários problemas de algumas aplicações que a gente tá construindo aqui na associação.

A associação tem mais de 75 anos e da pra imaginar quantas e o quão caóticas são as APIs que temos. Pra viabilizar a construção dos nossos protótipos tivemos que criar aplicações específicas pra eles que orquestram o consumo dessas APIs e possuem algumas lógicas de negócio da interface, como lidar com o estado de "lido" dos tutoriais, autenticar e servir as imagens que os usuários usam no perfil.

---

@kavalcante GraphQL é excelente! E fora a documentação que o esquema e os tipos oferecem ainda é possível usar intellisense e validar suas queries/mutations na compilação da aplicação front-end/mobile. E tem os clientes de GraphQL que facilitam muito a vida e melhoram a experiência com cache, e UI otimista*.