Créer votre première API avec Koa

Si vous connaissez JavaScript et souhaitez développer une API backend, Koa mérite qu’on s’y intéresse sérieusement. Il est minimaliste, moderne et construit autour d’async/await dès sa conception — ce qui signifie un code plus propre et l’absence de « callback hell ». Ce tutoriel sur les API Koa vous guide à travers les bases : la configuration d’un projet, la compréhension du fonctionnement des middlewares et la création d’une petite API REST avec des endpoints GET et POST.

Prérequis

• Node.js 20+ (version LTS actuelle recommandée)
• Connaissances de base en JavaScript, y compris async/await
• Un terminal et un éditeur de texte

Qu’est-ce que Koa et pourquoi l’utiliser ?

Koa est un framework web Node.js léger créé par l’équipe derrière Express. Contrairement à Express, Koa n’a pas de middleware intégré — vous n’ajoutez que ce dont vous avez besoin. Sa fonctionnalité distinctive est la cascade de middlewares, parfois appelée « modèle en oignon », où chaque fonction middleware exécute du code avant et après la suivante dans la chaîne.

Cela rend les bases de l’API Koa simples à comprendre : chaque requête traverse votre pile de middlewares vers l’intérieur, et la réponse ressort vers l’extérieur.

Étape 1 — Configurer votre projet

Créez un nouveau répertoire et initialisez-le :

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

Ajoutez "type": "module" à package.json pour utiliser la syntaxe des modules ES, puis installez les dépendances :

npm install koa @koa/router @koa/bodyparser

• koa — le framework principal
• @koa/router — middleware de routage officiel
• @koa/bodyparser — analyse les corps de requête JSON entrants

Étape 2 — Comprendre l’API middleware de Koa

Chaque middleware Koa est une fonction async qui reçoit un objet ctx (contexte) et une fonction next. L’objet ctx combine la requête et la réponse en un seul endroit — ctx.method, ctx.path, ctx.request.body et ctx.body (la réponse) y résident tous.

Appeler await next() transfère le contrôle au middleware suivant. Voici un exemple simple de journalisation :

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

Notez que le code après await next() s’exécute une fois que le middleware en aval a terminé. C’est le modèle en oignon en action.

Étape 3 — Créer une API REST avec Koa

Créez app.js avec une petite API d’articles en mémoire :

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

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

// Stockage de données en mémoire
let nextId = 3
let items = [
  { id: 1, name: "Keyboard" },
  { id: 2, name: "Monitor" },
]

// GET /items — retourne tous les articles
router.get("/items", (ctx) => {
  ctx.body = { success: true, data: items }
})

// GET /items/:id — retourne un article
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 — crée un nouvel article
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"))

Remarque : L’approche originale id: items.length + 1 échoue si vous supprimez un article, car la longueur du tableau diminue alors que les ID existants ne changent pas. Un compteur nextId séparé évite les ID en double.

Démarrez le serveur :

node app.js

Testez vos endpoints

Récupérer tous les articles :

curl http://localhost:3000/items

Créer un article :

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

Réponse attendue :

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

Demander un article manquant :

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

{ "error": "Item not found" }

router.allowedMethods() gère automatiquement les méthodes HTTP non prises en charge, renvoyant une réponse 405 Method Not Allowed appropriée sans code supplémentaire.

Conclusion

La force de Koa réside dans sa simplicité. L’objet ctx maintient la gestion des requêtes et des réponses en un seul endroit, et la cascade de middlewares vous donne un contrôle précis sur la façon dont les requêtes traversent votre application. Cette base — un serveur Koa, @koa/router pour le routage et @koa/bodyparser pour l’analyse JSON — est tout ce dont vous avez besoin pour commencer à créer une API REST avec Koa. À partir de là, vous pouvez ajouter une vraie base de données, de la validation ou un middleware de gestion d’erreurs, une couche à la fois.

FAQ

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.