A API do Voluntário Code Club Brasil é uma API de gestão de Code Clubes e Voluntários. Ela oferece funcionalidades para buscar Code Clubs, adicionar novos voluntários, fazer login na plataforma, enviar documentos e realizar operações de usuário.
- Node.js: A API é executada na plataforma Node.js na versão v18.15.0 .
- NestJS: O framework utilizado para desenvolver a API é o NestJS, que é um framework Node.js extensível e progressivo para construir aplicativos do lado do servidor eficientes e escaláveis a API está utilizando a versão v10.1.12.
- Linguagem TypeScript: A API é escrita em TypeScript, uma linguagem de programação fortemente tipada que compila para JavaScript. O TypeScript oferece recursos avançados de tipagem estática que tornam o código mais seguro e legível.
- ORM Prisma: O Prisma é utilizado como ORM (Object-Relational Mapping) para interagir com o banco de dados. Ele simplifica o acesso e a manipulação de dados do banco de dados, permitindo uma integração suave com o Node.js e TypeScript, a API está utilizando a versão 4.12.0.
- Banco de Dados PostgreSQL: A API utiliza o banco de dados relacional PostgreSQL para armazenar e gerenciar dados de voluntários, Code Clubs e outras informações essenciais. O PostgreSQL é conhecido por sua confiabilidade, desempenho e recursos avançados de SQL.
- Repositório Git: O código-fonte desta API. Você pode acessar o repositório no GitHub.
A API do Voluntário Code Club Brasil é desenvolvida com base na arquitetura Clean Architecture, também conhecida como Arquitetura Limpa. Essa abordagem arquitetural foi escolhida para promover a modularidade, a manutenibilidade e a escalabilidade do sistema, permitindo um desenvolvimento mais eficiente e uma estrutura bem organizada.
A Arquitetura Limpa segue vários princípios fundamentais que a tornam adequada para desenvolver aplicativos robustos e de alta qualidade:
-
Independência de Frameworks: A lógica de negócios é mantida independente de qualquer framework ou biblioteca específica, permitindo que você troque facilmente componentes de interface do usuário, armazenamento de dados ou outras partes do sistema.
-
Independente da IU: A UI pode mudar facilmente, sem alterar o resto do sistema. Uma UI da Web pode ser substituída por uma UI de console, por exemplo, sem alterar as regras de negócios.
-
Testabilidade: A arquitetura promove a testabilidade fácil, pois a lógica de negócios está isolada em camadas interiores, tornando simples escrever testes unitários e de integração.
-
Separação de Responsabilidades: A Clean Architecture divide o sistema em camadas bem definidas, como Entidades de Negócios, Casos de Uso, Adaptadores e Controladores, cada uma com sua responsabilidade clara. Isso melhora a compreensão e a manutenção do código.
-
Regra de Dependência: As dependências fluem das camadas externas para as camadas internas. Isso significa que as camadas internas, que contêm a lógica de negócios, não dependem das camadas externas, como frameworks ou bibliotecas.
-
Independente do banco de dados: Você pode trocar Oracle ou SQL Server por Mongo, BigTable, CouchDB ou qualquer outra coisa. Suas regras de negócios não estão vinculadas ao banco de dados.
-
Modelagem Orientada a Casos de Uso: A Clean Architecture se concentra em modelar os casos de uso do sistema, representando como os usuários interagem com o sistema e garantindo que essa interação seja clara e lógica.
A API do Voluntário Code Club Brasil é organizada de acordo com os princípios da Clean Architecture. Ela é dividida em camadas distintas, cada uma com seu próprio conjunto de responsabilidades:
-
Entidades de Negócios: Representam os objetos principais do domínio da aplicação, como voluntários, clubes e outros conceitos.
-
Casos de Uso: Contêm a lógica de negócios da aplicação, definindo como os casos de uso específicos devem ser tratados.
-
Adaptadores: São responsáveis pela interação com recursos externos, como bancos de dados, serviços web e interfaces de usuário. Eles traduzem as informações entre o formato interno da aplicação e o formato esperado pelos recursos externos.
-
Controladores: Gerenciam as solicitações HTTP, validam dados de entrada e encaminham as solicitações para os casos de uso apropriados.
Esta estrutura permite que a API seja altamente flexível, facilitando a adição de novos recursos, a manutenção e a evolução contínua do sistema.
| Comandos npm - Se preferir pode usar o yarn | Descrição |
|---|---|
npm install ou npm i |
Instala todos os pacotes para o projeto funcionar. |
npm run build |
Constroi o projeto. |
npm run format |
Por padrão, o nestjs utiliza o lint para deixar o código com a sintaxe e o estilo padrão. |
npm start ou npm run start:dev |
Ambos os comandos para inicializar o projeto, sendo npm run start:dev para a utilização do projeto atualizado em tempo real a cada alteração. |
| Comando docker compose | Descrição |
|---|---|
docker compose up -d |
Inicia um contêiner. |
docker compose stop |
Para de executar p contêiner. |
docker compose rm |
Remove os contêineres que estão pausados. |
| Comandos prisma | Descrição |
|---|---|
npx prisma migrate dev |
Criação de suas migrações, servindo para criar, atualizar ou excluir as tabelas ou campos de um determinado banco. |
npx prisma generate |
Gera o cliente Prisma. |
npx prisma db push |
Usado para sincronizar o esquema Prisma com o banco de dados. |
A estrutura de dados abaixo é usada para representar informações de voluntários na API do Voluntário Code Club Brasil. Cada campo possui um nome, tipo de dado e descrição para fornecer uma compreensão completa do JSON.
-
name (Nome do Voluntário):
- Tipo de Dado: String
- Descrição: O nome do voluntário.
-
lastName (Sobrenome do Voluntário):
- Tipo de Dado: String
- Descrição: O sobrenome do voluntário.
-
tels (Números de Telefone do Voluntário):
- Tipo de Dado: Array de Strings
- Descrição: Uma lista de números de telefone do voluntário. Pode conter vários números de telefone.
-
email (Endereço de E-mail do Voluntário):
- Tipo de Dado: String
- Descrição: O endereço de e-mail do voluntário.
-
password (Senha do Voluntário):
- Tipo de Dado: String
- Descrição: A senha do voluntário.
-
city (Cidade do Voluntário):
- Tipo de Dado: String
- Descrição: A cidade onde o voluntário reside.
-
state (Estado do Voluntário):
- Tipo de Dado: Enumeração (Estados Brasileiros)
- Descrição: O estado onde o voluntário reside. Deve ser um dos estados brasileiros, como "São Paulo," "Rio de Janeiro," etc.
-
neighborhood (Bairro do Voluntário):
- Tipo de Dado: String
- Descrição: O bairro onde o voluntário reside.
-
knowledges (Conhecimentos do Voluntário):
- Tipo de Dado: Array de Strings
- Descrição: Uma lista dos conhecimentos ou habilidades do voluntário. Pode incluir várias áreas de conhecimento, como programação, design, ensino, etc.
-
available_time (Disponibilidade de Horário do Voluntário):
- Tipo de Dado: Array de Objetos
- Descrição: Uma lista que representa a disponibilidade de horário do voluntário. Cada objeto contém os seguintes campos:
- week_day (Dia da Semana): Enumeração (Dias da Semana)
- Descrição: O dia da semana em que o voluntário está disponível.
- time_start (Horário de Início):
- Tipo de Dado: Datetime (HH:mm)
- Descrição: O horário de início em que o voluntário está disponível.
- time_end (Horário de Término):
- Tipo de Dado: Datetime (HH:mm)
- Descrição: O horário de término em que o voluntário está disponível.
- week_day (Dia da Semana): Enumeração (Dias da Semana)
Esta estrutura de dados é usada para representar informações de voluntários na API do Voluntário Code Club Brasil.
- Método: GET
- Descrição: Este endpoint permite buscar Code Clubs com base em critérios como nome, estado, cidade e bairro.
- Parâmetros:
-
name(opcional) - Nome do Code Club. -state(opcional) - Estado do Code Club. -city(opcional) - Cidade do Code Club. -neighborhood(opcional) - Bairro do Code Club. - Respostas:
-
200(OK) - Resposta bem-sucedida com informações sobre os Code Clubs. - Outros códigos de resposta para possíveis erros.
- Método: POST
- Descrição: Este endpoint permite adicionar um novo voluntário à plataforma.
- Payload:
{
"name": "string",
"last_name": "string",
"username": "string",
"telephone": [
"string"
],
"email": "string",
"password": "string",
"city": "string",
"state": "AC",
"neighborhood": "string",
"knowledges": [
"string"
],
"available_time": [
{
"week_day": "sunday",
"time_start": "2023-11-24T00:16:13.903Z",
"time_end": "2023-11-24T00:16:13.903Z"
}
],
"active": true,
"created_at": "2023-11-24T00:16:13.903Z",
"updated_at": "2023-11-24T00:16:13.903Z"
}- Respostas:
200(OK) - Resposta bem-sucedida com informações sobre o voluntário adicionado.405(Invalid input) - Erro de entrada inválida.
- Método: GET
- Descrição: Este endpoint permite aos voluntários fazerem login na plataforma.
- Parâmetros:
email(opcional) - O nome de usuário para fazer login.password(opcional) - A senha para fazer login em texto claro.
- Respostas:
200(OK) - Resposta bem-sucedida com informações de login.400(Invalid username/password supplied) - Nome de usuário ou senha inválidos.
- Método: POST (multipart/form-data)
- Descrição: Este endpoint permite aos voluntários enviar um novo documento para a plataforma.
- Payload: Envio de arquivo, incluindo um campo
fileName. - Respostas:
200(OK) - Resposta bem-sucedida.405(Invalid input) - Erro de entrada inválida.
- Método: GET
- Descrição: Este endpoint permite obter informações de usuário com base no nome de usuário.
- Parâmetros:
username(obrigatório) - O nome a ser buscado.
- Respostas:
200(OK) - Resposta bem-sucedida com informações do usuário.400(Invalid username supplied) - Nome de usuário inválido.404(User not found) - Usuário não encontrado.
- Método: PUT
- Descrição: Este endpoint permite atualizar as informações de um usuário existente (somente permitido para o usuário logado).
- Parâmetros:
username(obrigatório) - O nome do usuário a ser atualizado.
- Payload:
{
"name": "string",
"last_name": "string",
"password": "string",
"city": "string",
"state": "AC",
"neighborhood": "string",
"active": true,
"telephone": [
"string"
],
"email": "string"
}- Respostas:
200(OK) - Resposta bem-sucedida.- Outros códigos de resposta para possíveis erros.
- Autenticação JWT (Bearer Token) é necessária para os endpoints, conforme especificado.
Créditos: Esta documentação foi preparada por Victor Hugo para a API do Voluntário Code Club Brasil.