Como estruturar uma API do zero sem erro?

Para estruturar uma API do zero com qualidade, comece pelos requisitos funcionais, quebre cada funcionalidade em user stories, derive os requisitos técnicos dessas histórias e só então escolha a stack. Organize o código em camadas com arquitetura hexagonal e deixe o deploy para o fim do processo.

Requisitos funcionais antes da stack: por que a ordem importa

Para estruturar uma API do zero da forma certa, você começa pelos requisitos funcionais: as features que o projeto vai oferecer e o problema que ele resolve. A stack só entra depois, porque os requisitos técnicos são moldados pelo comportamento que o produto precisa ter.

No vídeo do Felipe Rocha, publicado em junho de 2026 no canal Full Stack Club, o exemplo é um SaaS de gestão de treinos de musculação. Antes de decidir entre TypeScript, Prisma ou PostgreSQL, a pergunta certa é: qual problema real essa aplicação resolve? No caso, a dificuldade de manter uma rotina de treino.

Dois conselhos práticos desse processo valem para qualquer projeto:

• Pegue uma ideia validada e melhore 20% ou 30%. Se ninguém no mercado faz o que você imagina, é mais provável que a ideia não tenha negócio do que você ter encontrado uma oportunidade revolucionária. Melhorar um produto que já existe reduz risco e custo.

• Foque em um único nicho. A analogia da padaria é direta: quem tenta vender pão, bolo, açaí e hambúrguer no primeiro dia não faz nada bem. Uma aplicação pequena que só cria e gerencia treinos entrega mais valor do que uma plataforma gigante e genérica.

User stories: como quebrar features em regras de negócio

User stories são a técnica de estruturar requisitos funcionais em frases com ator, ação e objetivo. Cada história carrega suas próprias regras de negócio, e é nelas que o comportamento da API começa a ficar concreto.

Exemplos do próprio vídeo: "eu, como usuário, quero criar um programa de treino" ou "quero marcar um treino como concluído". Dentro da primeira história, pode existir uma regra como "só é permitido criar programas de treino com data futura". Você detalha as regras antes de escrever qualquer linha de código.

Esse detalhamento muda a engenharia. A história "eu, como usuário, quero receber notificações dos meus treinos" já sugere uma arquitetura de publicação e assinatura: talvez uma fila como o Amazon SQS ou uma ferramenta de tarefas agendadas como o Trigger.dev, opção mais simples mas com custo maior. A regra de negócio, e não a preferência pessoal, escolhe a ferramenta.

Requisitos técnicos: estimando carga, tempo de resposta e custo

Os requisitos técnicos derivam dos funcionais e incluem métricas de desempenho, orçamento e carga esperada. Em projetos de consultoria, o cliente costuma entregar esses números prontos; no seu próprio produto, você os elabora.

Um requisito típico é tempo médio de resposta: digamos, no máximo 200 milissegundos por rota. Se a meta fosse 50 milissegundos, você provavelmente precisaria de cache com Redis para atingir o objetivo.

A estimativa de carga é aritmética simples. Suponha 1.000 usuários diários fazendo três operações cada um: entrar, acessar um treino e marcá-lo como concluído. Isso dá 3.000 requisições por dia. Dividindo por 24 horas, chega a 125 requisições por hora, cerca de duas por minuto. Com esse volume, não há motivo para réplicas de banco de dados, balanceador de carga ou múltiplas instâncias da API.

Há também um ponto honesto no vídeo: se você não sabe quantos usuários sua aplicação terá, provavelmente ainda não tem audiência, e o volume será pequeno. Comece com uma stack simples e evolua quando a demanda aparecer.

É aqui que escolhas de produto aparecem na técnica: se a aplicação precisa aparecer nas buscas do Google, um React com Vite não basta. O requisito funcional de SEO puxa para o Next.js, que oferece renderização no servidor e geração estática.

Comece simples, mas não escreva código porco

A recomendação para o início de qualquer projeto é começar o mais simples possível, sem cair em código porco: tudo acoplado, regra de negócio misturada com chamada de banco e camada de apresentação, e nenhum teste.

A justificativa para pular testes era o tempo em um MVP. Em 2026, essa desculpa perdeu força: agentes de IA escrevem testes rapidamente, e escrevê-los bem é justamente uma das tarefas em que eles mais ajudam. O custo de manter qualidade caiu; o custo de consertar código acoplado continua alto.

Termos como clean architecture, domain driven design (DDD) e princípios SOLID têm seu lugar, mas não no primeiro dia de um MVP. Arquitetura hexagonal, por outro lado, o autor trata como o mínimo que qualquer projeto deve ter desde o começo.

Arquitetura hexagonal na prática: drivers, application e resources

A arquitetura hexagonal, também chamada de ports and adapters, divide a aplicação em três camadas: drivers, application e resources. Pense nas camadas como conjuntos de classes, já que o padrão se apoia em programação orientada a objetos.

Cada camada tem uma responsabilidade clara:

• Drivers: a borda de entrada. Em uma API com Fastify, são as rotas; em um app Next.js, as server actions também podem ser drivers.

• Application: os use cases, onde vive a regra de negócio. Exemplo: o caso de uso de criar usuário contém a regra de não cadastrar e-mail já existente e a validação de senha igual à confirmação.

• Resources: os recursos externos, como o banco PostgreSQL e filas. Aqui entra o padrão repository: uma classe que interage com o banco e converte o resultado de selects e inserts em um objeto de domínio.

Entre as camadas ficam as portas e adaptadores, que são interfaces. No código de exemplo do vídeo, um use case recebe uma interface como dependência; passar a implementação concreta na instanciação é injeção de dependência, e depender da interface é inversão de dependência. Para um MVP, o autor considera a injeção suficiente, sem precisar inverter tudo formalmente.

Sobre modelagem de domínio: entities e value objects fazem sentido em DDD, mas em um MVP basta uma entidade simples de usuário, sem classes cheias de regras. Avanço de complexidade deve acompanhar a necessidade real do produto.

Deploy: hospedagem simples para APIs Node

O vídeo fecha com o segmento patrocinado pela Hostinger, que segundo o autor oferece um plano de cerca de R$ 14 por mês com máquina de dois núcleos de CPU e 3 GB de memória, além de servidores e CDN na América do Sul. Trata-se de relato do próprio criador, não de medição independente.

O fluxo destacado é conectar a aplicação Node ao repositório no GitHub e fazer o deploy pela própria plataforma. Para um MVP com a carga estimada de duas requisições por minuto, uma máquina desse porte atende bem; migração para infraestrutura maior só faz sentido quando os números de uso justificarem. Conteúdos de outras escolas brasileiras, como o Crazystack Typescript e o Bootcamp do Dev Doido, do criador Gustavo Dev Doido, abordam temas parecidos de backend e deploy, o que mostra que o processo de estruturar API é recorrente no mercado — confira sempre o site oficial de cada curso antes de decidir.

Perguntas frequentes sobre estruturar APIs

• Devo usar clean architecture ou DDD desde o início? Não. Para um MVP, arquitetura hexagonal com use cases, repositories e injeção de dependência já basta. DDD com entities e value objects entra quando a complexidade do domínio realmente pedir.

• Quantas requisições por dia justificam réplicas de banco? Depende do perfil de carga, mas o exemplo do vídeo mostra o raciocínio: 3.000 requisições diárias equivalem a cerca de duas por minuto, volume que não exige réplicas, balanceador de carga nem múltiplas instâncias.

• Por que requisitos funcionais vêm antes da stack? Porque os requisitos técnicos são moldados pelos funcionais. Se a aplicação precisa aparecer no Google, você escolhe Next.js por renderização no servidor; se precisa responder em 50 ms, você adiciona cache.

• O que é um código porco? É código totalmente acoplado, com regra de negócio, chamada de banco e apresentação misturadas na mesma camada, e sem testes. Ele dificulta qualquer evolução e é evitável com separação simples em camadas.

• Arquitetura hexagonal serve só para backend? Não. O mesmo modelo de drivers, application e resources funciona em aplicações Next.js, em que as server actions exercem o papel de drivers chamando use cases.

Transforme explicações em vídeo em artigos escritos

O método deste artigo, requisitos primeiro, técnica depois, é o tipo de conteúdo que merece existir em texto também. Se você explica arquitetura, código ou produto em vídeos, esse conhecimento fica preso em 20 minutos de áudio que ninguém consegue buscar ou citar.

Com o Skala Blog, você cola a URL de um vídeo do YouTube, o conteúdo é transcrito e vira um artigo estruturado, pronto para revisar e publicar. Vale para aulas, entrevistas e aquele passo a passo que só existe na sua cabeça e no seu canal.

Source video