API REST para consulta de materiais. Desenvolvida com Node.js, Express e TypeScript, expõe um endpoint paginado para listagem de materiais cadastrados no banco de dados PostgreSQL.
A API é hospedada no Railway e conta com documentação interativa via Swagger UI, CORS configurado por ambiente, health check e ready check para monitoramento de disponibilidade.
✔️ Listagem paginada de materiais com suporte a limit e page
✔️ Validação de parâmetros de query com retorno de erro 400 descritivo
✔️ Health check (/health) para verificar se a aplicação está viva
✔️ Ready check (/ready) com validação de conectividade com o banco
✔️ CORS configurado por ambiente via variável ALLOWED_ORIGINS
✔️ Middleware de tratamento de erros centralizado com AppError
✔️ Documentação interativa disponível em /api-docs (Swagger UI)
O projeto segue separação por camadas (layered architecture), onde cada responsabilidade vive em seu próprio diretório dentro de src/.
src/
├── config/
│ ├── db.ts # Pool de conexão PostgreSQL
│ ├── env.ts # Validação e exposição de variáveis de ambiente
│ └── swagger.ts # Spec OpenAPI 3.0 (schemas + paths)
│
├── routes/
│ └── materiais.ts # Definição da rota GET /materiais com JSDoc @openapi
│
├── controllers/
│ └── materiaisController.ts # Validação de query params e orquestração
│
├── services/
│ └── materiaisService.ts # Regras de negócio e mapeamento para DTO
│
├── models/
│ └── Material.ts # Acesso ao banco (queries SQL)
│
├── middlewares/
│ └── errorHandler.ts # Tratamento centralizado de erros
│
├── types/
│ └── material.ts # Interfaces Material e MaterialDTO
│
└── index.ts # Bootstrap da aplicação
| Método | Rota | Descrição |
|---|---|---|
GET |
/materiais |
Lista materiais com paginação |
Query params de /materiais:
| Parâmetro | Tipo | Obrigatório | Padrão | Máximo | Descrição |
|---|---|---|---|---|---|
limit |
integer | Não | 50 |
100 |
Itens por página |
page |
integer | Não | 1 |
— | Número da página |
Resposta 200:
{
"data": [{ "id": 1, "nomeMaterial": "Cimento CP-II", "codigo": "CIM001" }],
"total": 200,
"limit": 50,
"offset": 0
}Resposta 400 (parâmetro inválido):
{ "error": "O parâmetro limit deve ser um número maior que 0" }| Método | Rota | Descrição |
|---|---|---|
GET |
/health |
Retorna 200 se a aplicação está no ar |
GET |
/ready |
Retorna 200 se o banco está acessível, 503 caso contrário |
git clone https://github.com/warlleyrocha/api-materiais.git
cd api-materiaisnpm installcp .env.example .env
# Edite o .env com sua DATABASE_URL e demais variáveisnpm run devnpm run build
npm start| Script | O que faz |
|---|---|
npm run dev |
Inicia com nodemon + ts-node (hot reload) |
npm run build |
Compila TypeScript para dist/ |
npm start |
Executa o build compilado |
| Variável | Obrigatória | Padrão | Descrição |
|---|---|---|---|
DATABASE_URL |
Sim | — | String de conexão PostgreSQL |
PORT |
Não | 3000 |
Porta em que o servidor sobe |
ALLOWED_ORIGINS |
Não | * |
Origens permitidas no CORS, separadas por vírgula |
Exemplo de .env:
DATABASE_URL=postgresql://usuario:senha@host:porta/database
PORT=3000
ALLOWED_ORIGINS=https://meuapp.com,https://outro.comCom a aplicação rodando, acesse:
http://localhost:3000/api-docs
A documentação é gerada automaticamente via Swagger UI com base na spec OpenAPI 3.0 definida em src/config/swagger.ts e nas anotações @openapi das rotas.
| Tecnologia | Uso |
|---|---|
| Node.js | Runtime |
| TypeScript | Tipagem estática |
| Express | Framework HTTP |
| node-postgres (pg) | Cliente PostgreSQL |
| dotenv | Carregamento de variáveis de ambiente |
| cors | Middleware de CORS |
| swagger-jsdoc | Geração de spec OpenAPI a partir do código |
| swagger-ui-express | Interface interativa da documentação |
| Railway | Deploy e banco de dados em produção |
 Warlley Rocha |
|---|
O arquivo de licença será adicionado posteriormente ao repositório.