Construindo Sua Primeira API com Koa

Se você conhece JavaScript e quer construir uma API backend, o Koa merece uma análise séria. É minimalista, moderno e construído em torno de async/await desde o início—o que significa código mais limpo e sem callback hell. Este tutorial de API Koa guia você pelos conceitos básicos: configurar um projeto, entender como o middleware funciona e construir uma pequena API REST com endpoints GET e POST.

Pré-requisitos

• Node.js 20+ (versão LTS atual recomendada)
• Conhecimento básico de JavaScript, incluindo async/await
• Um terminal e um editor de texto

O Que É Koa e Por Que Usá-lo?

Koa é um framework web Node.js leve criado pela equipe por trás do Express. Diferentemente do Express, o Koa não possui middleware integrado—você adiciona apenas o que precisa. Sua característica marcante é a cascata de middleware, às vezes chamada de “modelo de cebola”, onde cada função de middleware executa código antes e depois da próxima na cadeia.

Isso torna os conceitos básicos da API do Koa diretos de entender: cada requisição flui para dentro através da sua pilha de middleware, e a resposta flui de volta para fora.

Passo 1 — Configure Seu Projeto

Crie um novo diretório e inicialize-o:

mkdir koa-items-api && cd koa-items-api
npm init -y

Adicione "type": "module" ao package.json para usar a sintaxe de módulos ES, depois instale as dependências:

npm install koa @koa/router @koa/bodyparser

• koa — o framework principal
• @koa/router — middleware oficial de roteamento
• @koa/bodyparser — analisa corpos de requisição JSON recebidos

Passo 2 — Entenda a API de Middleware do Koa

Todo middleware Koa é uma função async que recebe um objeto ctx (contexto) e uma função next. O objeto ctx combina a requisição e a resposta em um único lugar—ctx.method, ctx.path, ctx.request.body e ctx.body (a resposta) ficam todos ali.

Chamar await next() passa o controle para o próximo middleware. Aqui está um exemplo simples de logging:

app.use(async (ctx, next) => {
  const start = Date.now()
  await next()
  console.log(`${ctx.method} ${ctx.path} — ${Date.now() - start}ms`)
})

Note que o código após await next() executa quando o middleware downstream terminou. Esse é o modelo de cebola em ação.

Passo 3 — Construa uma API REST com Koa

Crie app.js com uma pequena API de itens em memória:

import Koa from "koa"
import Router from "@koa/router"
import  bodyParser  from  "@koa/bodyparser"

const app = new Koa()
const router = new Router()

// Armazenamento de dados em memória
let nextId = 3
let items = [
  { id: 1, name: "Keyboard" },
  { id: 2, name: "Monitor" },
]

// GET /items — retorna todos os itens
router.get("/items", (ctx) => {
  ctx.body = { success: true, data: items }
})

// GET /items/:id — retorna um item
router.get("/items/:id", (ctx) => {
  const item = items.find((i) => i.id === Number(ctx.params.id))
  if (!item) {
    ctx.status = 404
    ctx.body = { error: "Item not found" }
    return
  }
  ctx.body = { success: true, data: item }
})

// POST /items — cria um novo item
router.post("/items", (ctx) => {
  const { name } = ctx.request.body
  if (!name) {
    ctx.status = 400
    ctx.body = { error: "Name is required" }
    return
  }
  const newItem = { id: nextId++, name }
  items.push(newItem)
  ctx.status = 201
  ctx.body = { success: true, data: newItem }
})

app.use(bodyParser())
app.use(router.routes())
app.use(router.allowedMethods())

app.listen(3000, () => console.log("Server running on http://localhost:3000"))

Nota: A abordagem original id: items.length + 1 falha se você deletar um item, porque o comprimento do array diminui enquanto os IDs existentes não. Um contador nextId separado evita IDs duplicados.

Inicie o servidor:

node app.js

Teste Seus Endpoints

Obter todos os itens:

curl http://localhost:3000/items

Criar um item:

curl -X POST http://localhost:3000/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Mouse"}'

Resposta esperada:

{ "success": true, "data": { "id": 3, "name": "Mouse" } }

Solicitar um item inexistente:

curl http://localhost:3000/items/99

{ "error": "Item not found" }

router.allowedMethods() trata métodos HTTP não suportados automaticamente, retornando uma resposta apropriada 405 Method Not Allowed sem código extra.

Conclusão

A força do Koa é sua simplicidade. O objeto ctx mantém o tratamento de requisição e resposta em um único lugar, e a cascata de middleware oferece controle preciso sobre como as requisições fluem através da sua aplicação. Esta base—um servidor Koa, @koa/router para roteamento e @koa/bodyparser para análise de JSON—é tudo que você precisa para começar a construir uma API REST com Koa. A partir daqui, você pode adicionar um banco de dados real, validação ou middleware de tratamento de erros uma camada por vez.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.