Enhancements

[filhocodes]

Eu proponho as seguintes melhorias a API de eventos, e ao site.

Alterações gerais

• Renomear de eventos-api para sapucaia-api ou sapucaiatech/api, pois não serão apenas eventos que a API retornará
• Mover o código do projeto para a especificação ECMA mais recente, utilizando Babel com o babel-preset-env (ele vai manter as especificações que o Node.js aceita e transformar apenas as outras, e configuramos para ainda utilizar o Nodemon, ou WebPack com Hot Reloading do server).
• Implementar debug para logs e instrumentação simples.
• Implementar um módulo de controle de erros
• Implementar mais usuários, com registro de ação
• Implementar o parametro incluir. Por exemplo, se eu requisitar /encontros?incluir=palestras (ver proposta do endpoint lá em baixo), ao invés da resposta apresentar links que retornam as palestras de determinado encontro, já incluir as palestras na resposta.
• Documentar os recursos da API

Endpoint /eventos

• Retornar 201 na requisição POST (https://httpstatuses.com/201)
• Retornar 400 em POST e PUT caso o formato do JSON enviado não for válido. Podemos usar algo como Joi para validar o JSON enviado. Isso ganha importância no momento que você decide passar req.body inteiro ao model, no lugar de escolher os campos que você quer salvar.
• Trocar os parâmetros after e before por anterior_a e posterior_a (ou sem o adjunto), ou mover todas as rotas para o inglês para criar consistência.
• Retornar 400 em GET caso o formato de uma data informada não for válida.
• Pensar em paginação.
• Mudar /eventos/passados para /eventos?anterior_a=hoje (com redirecionamento 301 no caminho antigo), para manter apenas uma função de busca
• Criar um módulo que abstrai as funções de busca diretamente ao model. Exemplo, no lugar de usar Evento.find().sort() e Evento.findOneAndUpdate(), manter um módulo que abstraia o conjunto de instruções para Eventos.find(dateA, dateB), e Eventos.update(id, data). Isso separa responsabilidades (o código que interpreta uma requisição HTTP do código que manipula dados).

Propostas para novos endpoints:

• /encontros, para listar apenas os encontros do Sapucaia Tech. Deve ter local, data, palestrantes, link para a resposta de palestras. Não utilizar /eventos?comunidade=sapucaia, porque em /encontros retornaríamos mais dados do que apenas sinopse e local, sendo um recurso diferente para que possamos exibir no site melhores informações (já que eventos de terceiros apenas redirecionamos para o site do mesmo).
• /encontros/palestrantes, para listar todos os palestrantes, ministradores de cursos, workshops, dojos, etc, apenas de eventos do Sapucaia Tech (ou podemos fazer um /palestrantes que lista todo mundo e um /palestrantes?evento=sapucaia&evento_edicao=3 para ter apenas os de certo evento, e palestrantes como por exemplo Zeno Rocha que nunca palestrou no sapucaia não teria um link para palestrantes/:id/palestras para conseguimos manter um padrão de recurso). Na resposta de um palestrante, conter um link que retorna todas as palestras que ele fez.
• /encontros/:id/palestras e /encontro/palestrantes/:id/palestras, para retornar as palestras de um encontro ou palestrante. As palestras podem ter tipo (palestra, encontro, debate, dojo, workshop, miniaula, videoaula, etc), evento, palestrante, titulo, tema, sinopse, link para gravação, link para arquivos, slides, etc)
• /encontros/palestras?pesquisa= (ou /palestras?pesquisa=, mas aí neste caso deveriamos ter também palestras que não são do encontro e seria um recurso mais dificil de manter padronizado e populado), permite pesquisar por determinadas palestras através do titulo e do tema. Podemos também bloquear o endpoint para funcionar apenas como pesquisa (retornando 400 caso o termo não for informado), e pode ser útil para pessoas que procuram estudar sobre um assunto.
• /professores (eu não sei que nome chamar, definam aí), permite pesquisar por pessoas que se dispõe a manter um contato aberto para tirar duvidas e interagir fora de encontros e eventos. Por exemplo, Gabriel aceita ensinar a quem procura sobre HTTP, ele ganharia uma página no site com a foto dele, resumo, forma de contato, e quem tiver alguma duvida vai entrar em contato e ele vai ajudar.
• /vagas - painel de vagas no Brasil inteiro. A vaga teria uma validade padrão, tipo um mês, porque caso for tipo uma vaga repassada e quem publicou não sabe se ela foi preenchida ou não a API pararia de retornar ela (a não ser que a pessoa renove a vaga para que ela fique em aberta), e resolveria o problema de esquecermos de manter uma vaga atualizada, ou que não temos contato com os responsáveis, ou algo assim.
• /profissionais - painel de profissionais que oferecem serviços.
• /wiki - Local aberto para busca de conteúdo. Preferi wiki a blog ou forum, pois acho que o nome aceita um leque maior de possibilidade como por exemplo Heberth gravar video aulas sobre indexação de banco de dados e postar, e Gabriel repostar posts do blog dele, e o "Podcast dev com pequi".

Site

Sei que tem o repositório, por isso não inclui como task list, mas estou listando para justificar as propostas acimas

• Os encontros, palestras, e pesquisa seriam inseridos no site. Mover para uma SPA ou algo como Next/Nuxt para ter todas essas páginas.
• A pagina de conduta podia estar no site também
• Poderíamos exibir as ultimas mensagens do Telegram.

A discussão está aberta 😃

[filhocodes]

Nota pessoal, sou contra /professores, pois acho que dúvidas assim poderiam ser jogadas em um canal de mensagem aberto (Forum, Telegram, Slack), mas listei porque vocês podem visualizar uma possibilidade que não percebi

[filhocodes]

/cc @gabsprates @edumrodrigues @danielmadu