Construyendo tu Primera API con Koa

Si conoces JavaScript y quieres construir una API backend, Koa merece una consideración seria. Es minimalista, moderno y construido sobre async/await desde cero, lo que significa código más limpio y sin el infierno de callbacks. Este tutorial de API con Koa te guía a través de los conceptos básicos: configurar un proyecto, entender cómo funciona el middleware y construir una pequeña API REST con endpoints GET y POST.

Requisitos Previos

• Node.js 20+ (se recomienda la versión LTS actual)
• Conocimientos básicos de JavaScript, incluyendo async/await
• Una terminal y un editor de texto

¿Qué es Koa y Por Qué Usarlo?

Koa es un framework web ligero de Node.js creado por el equipo detrás de Express. A diferencia de Express, Koa no tiene middleware incluido—añades solo lo que necesitas. Su característica distintiva es la cascada de middleware, a veces llamada “modelo de cebolla”, donde cada función de middleware ejecuta código antes y después del siguiente en la cadena.

Esto hace que los conceptos básicos de la API de Koa sean directos de razonar: cada petición fluye hacia adentro a través de tu pila de middleware, y la respuesta fluye de vuelta hacia afuera.

Paso 1 — Configura tu Proyecto

Crea un nuevo directorio e inicialízalo:

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

Añade "type": "module" a package.json para usar la sintaxis de módulos ES, luego instala las dependencias:

npm install koa @koa/router @koa/bodyparser

• koa — el framework principal
• @koa/router — middleware oficial de enrutamiento
• @koa/bodyparser — analiza los cuerpos de petición JSON entrantes

Paso 2 — Entiende la API de Middleware de Koa

Cada middleware de Koa es una función async que recibe un objeto ctx (contexto) y una función next. El objeto ctx combina la petición y la respuesta en un solo lugar—ctx.method, ctx.path, ctx.request.body y ctx.body (la respuesta) viven allí.

Llamar a await next() pasa el control al siguiente middleware. Aquí hay un ejemplo simple de registro:

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

Observa que el código después de await next() se ejecuta una vez que el middleware posterior ha terminado. Ese es el modelo de cebolla en acción.

Paso 3 — Construye una API REST con Koa

Crea app.js con una pequeña API de items en memoria:

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

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

// Almacén de datos en memoria
let nextId = 3
let items = [
  { id: 1, name: "Keyboard" },
  { id: 2, name: "Monitor" },
]

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

// GET /items/:id — devuelve un 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 — crea un nuevo 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: El enfoque original id: items.length + 1 falla si alguna vez eliminas un item, porque la longitud del array se reduce mientras que los IDs existentes no. Un contador nextId separado evita IDs duplicados.

Inicia el servidor:

node app.js

Prueba tus Endpoints

Obtener todos los items:

curl http://localhost:3000/items

Crear un item:

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

Respuesta esperada:

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

Solicitar un item inexistente:

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

{ "error": "Item not found" }

router.allowedMethods() maneja automáticamente los métodos HTTP no soportados, devolviendo una respuesta apropiada 405 Method Not Allowed sin código adicional.

Conclusión

La fortaleza de Koa es su simplicidad. El objeto ctx mantiene el manejo de petición y respuesta en un solo lugar, y la cascada de middleware te da control preciso sobre cómo fluyen las peticiones a través de tu aplicación. Esta base—un servidor Koa, @koa/router para enrutamiento y @koa/bodyparser para análisis JSON—es todo lo que necesitas para comenzar a construir una API REST con Koa. Desde aquí, puedes añadir una base de datos real, validación o middleware de manejo de errores una capa a la vez.

Preguntas Frecuentes

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.