Task API Tutorial

Finished projectCopy Anchor Link

By the end, port 8080 answers like this:

The same flow, as curl commands:

curl -X POST http://localhost:8080/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"Write the docs"}'
# → {"id":1,"title":"Write the docs","done":false}

curl http://localhost:8080/tasks
# → [{"id":1,"title":"Write the docs","done":false}]

curl http://localhost:8080/tasks/1
# → {"id":1,"title":"Write the docs","done":false}

curl -i http://localhost:8080/tasks/999
# → HTTP/1.1 404 Not Found

The 999 miss returning a real 404 is the point — the GET hands back what the POST stored. Hand-wired on purpose so router, store, and middleware order stay visible. Prefer a scaffold? → Quick Start — scaffold with create-nextrush.

The request pipelineCopy Anchor Link

Every request above walks this path. Each part lights up one more stage:

Same shape as every NextRush app — not Task-API-specific.

Why a Task APICopy Anchor Link

A one-route hello-world stops too early. A Task API forces four backend concerns at once:

• Storage — remember state between requests
• Input — parse and validate a POST body before you trust it
• Lookup — resolve a route param, or fail honestly
• Errors — real HTTP 400 / 404, not silent bugs

Build those four once; Users and Orders reuse the same shape.

PrerequisitesCopy Anchor Link

Routing and Context are introduced as you need them. Beginner · ~20 minutes · 5 steps.

Create the applicationCopy Anchor Link

1. 1Part 1
2. 2Part 2
3. 3Part 3

Goal: Adapter → Router → Handler end to end. No storage, no body parsing yet.

mkdir task-api && cd task-api
pnpm init

$ pnpm add nextrush @nextrush/body-parser
$ pnpm add -D tsx typescript @types/node

import { createApp, createRouter, listen } from 'nextrush';

const app = createApp();
const router = createRouter();

router.get('/', (ctx) => {
  ctx.json({ name: 'Task API', status: 'ok' });
});

app.route('/', router);
await listen(app, 8080);

npx tsx src/index.ts

curl http://localhost:8080/
# → {"name":"Task API","status":"ok"}

Accept dataCopy Anchor Link

1. ✓Part 1
2. 2Part 2
3. 3Part 3

Goal: fixed-response server → one that remembers something.

  const app = createApp();
+ app.use(json());

  const router = createRouter();
+ router.post('/tasks', (ctx) => { ... });
+ router.get('/tasks', (ctx) => { ... });

import { createApp, createRouter, listen, BadRequestError } from 'nextrush';
import { json } from '@nextrush/body-parser';

type Task = { id: number; title: string; done: boolean };

const tasks = new Map<number, Task>();
let nextId = 1;

const app = createApp();

// Parse JSON bodies before any route runs — without this, ctx.body stays undefined.
app.use(json());

const router = createRouter();

router.get('/tasks', (ctx) => {
  ctx.json([...tasks.values()]);
});

router.post('/tasks', (ctx) => {
  const body = ctx.body as { title?: string };
  if (!body?.title) throw new BadRequestError('title is required');

  const task: Task = { id: nextId++, title: body.title, done: false };
  tasks.set(task.id, task);

  ctx.status = 201;
  ctx.json(task);
});

app.route('/', router);
await listen(app, 8080);

curl -X POST http://localhost:8080/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"Write the docs"}'
# → {"id":1,"title":"Write the docs","done":false}

curl -X POST http://localhost:8080/tasks \
  -H 'Content-Type: application/json' \
  -d '{}'
# → HTTP/1.1 400 Bad Request

🎉Part 2 complete — your API accepts JSON, stores tasks, and rejects bad input with a real 400.

Can you explain: why throw BadRequestError instead of ctx.json({ error: '...' }) with a 200?

(The HTTP status is what clients check first — burying the signal in a 200 body forces every caller to re-implement what NextRush already gives you.)

Read it back, honestlyCopy Anchor Link

1. ✓Part 1
2. ✓Part 2
3. 3Part 3

Goal: create → read back → honest miss.

  router.get('/tasks', (ctx) => {
    ctx.json([...tasks.values()]);
  });

+ router.get('/tasks/:id', (ctx) => {
+   const task = tasks.get(Number(ctx.params.id));
+   if (!task) throw new NotFoundError('Task not found');
+   ctx.json(task);
+ });

import { createApp, createRouter, listen, BadRequestError, NotFoundError } from 'nextrush';
import { json } from '@nextrush/body-parser';

type Task = { id: number; title: string; done: boolean };

const tasks = new Map<number, Task>();
let nextId = 1;

const app = createApp();
app.use(json());

const router = createRouter();

router.get('/tasks', (ctx) => {
  ctx.json([...tasks.values()]);
});

router.post('/tasks', (ctx) => {
  const body = ctx.body as { title?: string };
  if (!body?.title) throw new BadRequestError('title is required');

  const task: Task = { id: nextId++, title: body.title, done: false };
  tasks.set(task.id, task);

  ctx.status = 201;
  ctx.json(task);
});

router.get('/tasks/:id', (ctx) => {
  const task = tasks.get(Number(ctx.params.id));
  if (!task) throw new NotFoundError('Task not found');
  ctx.json(task);
});

app.route('/', router);
await listen(app, 8080);

curl -X POST http://localhost:8080/tasks \
  -H 'Content-Type: application/json' -d '{"title":"Write the docs"}'
# → {"id":1,...}

curl http://localhost:8080/tasks/1
# → {"id":1,...}

curl -i http://localhost:8080/tasks/999
# → HTTP/1.1 404 Not Found

task-api/
  package.json
  src/
    index.ts

If POST is empty, re-check app.use(json()) above the router. If a stored task 404s, re-check Number(ctx.params.id) against the id POST returned.

Final projectCopy Anchor Link

Architecture recapCopy Anchor Link

One last mental model — every box from Parts 1–3, live:

import { createApp, createRouter, listen, BadRequestError, NotFoundError } from 'nextrush';
import { json } from '@nextrush/body-parser';

type Task = { id: number; title: string; done: boolean };

const tasks = new Map<number, Task>();
let nextId = 1;

const app = createApp();
app.use(json());

const router = createRouter();

router.get('/tasks', (ctx) => {
  ctx.json([...tasks.values()]);
});

router.post('/tasks', (ctx) => {
  const body = ctx.body as { title?: string };
  if (!body?.title) throw new BadRequestError('title is required');

  const task: Task = { id: nextId++, title: body.title, done: false };
  tasks.set(task.id, task);

  ctx.status = 201;
  ctx.json(task);
});

router.get('/tasks/:id', (ctx) => {
  const task = tasks.get(Number(ctx.params.id));
  if (!task) throw new NotFoundError('Task not found');
  ctx.json(task);
});

app.route('/', router);
await listen(app, 8080);

Run it in the browser, no local setup:

Try: empty list → create → read by id → GET /tasks/999 for the honest 404.

Common mistakesCopy Anchor Link

What you builtCopy Anchor Link

• ✓ Application — createApp(), owns the middleware pipeline
• ✓ Router — createRouter(), mounted with app.route()
• ✓ Store — in-memory Map across requests
• ✓ Three routes — GET /tasks, POST /tasks, GET /tasks/:id
• ✓ Two error paths — real 400 and real 404

What you learnedCopy Anchor Link

Mental models (not the file list):

• Request pipeline — Adapter → Middleware → Router → Handler → Context
• Routing — params + mount — Routing
• Context — ctx.body, ctx.params, ctx.json(), ctx.status — Context
• Middleware order — parser before router or ctx.body is empty — Middleware
• Errors — throw HttpError, framework maps status — Error handling

A bigger app is this same pipeline with more middleware and more routes — not a different shape.

🎓 Think like an architectCopy Anchor Link

You've finished building. Now explain why it works — that's what separates copying from understanding.

Try it yourselfCopy Anchor Link

Extend the API at your level — Starter through Expert if you can. Don't peek until you've tried. Each solution builds on the one before it.

SolutionsCopy Anchor Link

Peek only after you've tried. Each builds on the previous level.

router.delete('/tasks/:id', (ctx) => {
  const existed = tasks.delete(Number(ctx.params.id));
  if (!existed) throw new NotFoundError('Task not found');

  ctx.status = 204;
  ctx.send('');
});

curl -i -X DELETE http://localhost:8080/tasks/1
# → HTTP/1.1 204 No Content

curl -i -X DELETE http://localhost:8080/tasks/999
# → HTTP/1.1 404 Not Found

router.put('/tasks/:id', (ctx) => {
  const id = Number(ctx.params.id);
  const existing = tasks.get(id);
  if (!existing) throw new NotFoundError('Task not found');

  const body = ctx.body as { title?: string; done?: boolean };
  if (!body?.title) throw new BadRequestError('title is required');

  const updated: Task = { id, title: body.title, done: body.done ?? existing.done };
  tasks.set(id, updated);
  ctx.json(updated);
});

curl -X PUT http://localhost:8080/tasks/1 \
  -H 'Content-Type: application/json' \
  -d '{"title":"Ship the tutorial","done":true}'
# → {"id":1,"title":"Ship the tutorial","done":true}

export type Task = { id: number; title: string; done: boolean };

export function createTaskRepository() {
  const tasks = new Map<number, Task>();
  let nextId = 1;

  return {
    create(title: string): Task {
      const task: Task = { id: nextId++, title, done: false };
      tasks.set(task.id, task);
      return task;
    },
    findById(id: number): Task | undefined {
      return tasks.get(id);
    },
    findAll(): Task[] {
      return [...tasks.values()];
    },
    delete(id: number): boolean {
      return tasks.delete(id);
    },
  };
}

const repo = createTaskRepository();
      
Copy Text
const repo: {
    create(title: string): Task;
    findById(id: number): Task | undefined;
    findAll(): Task[];
    delete(id: number): boolean;
}

import { createTaskRepository } from './task-repository.js';

const tasks = createTaskRepository();

router.get('/tasks', (ctx) => {
  ctx.json(tasks.findAll());
});

router.post('/tasks', (ctx) => {
  const body = ctx.body as { title?: string };
  if (!body?.title) throw new BadRequestError('title is required');

  const task = tasks.create(body.title);
  ctx.status = 201;
  ctx.json(task);
});

router.get('/tasks/:id', (ctx) => {
  const task = tasks.findById(Number(ctx.params.id));
  if (!task) throw new NotFoundError('Task not found');
  ctx.json(task);
});

import type { Context } from 'nextrush';

export function requestLogger() {
  return async (ctx: Context) => {
    console.log(`→ ${ctx.method} ${ctx.path}`);
    await ctx.next();
  };
}

import { requestLogger } from './middleware/request-logger.js';

const app = createApp();
app.use(json()); // parse bodies before anything that reads ctx.body
app.use(requestLogger());

const router = createRouter();
// ... routes unchanged ...

Next tutorialCopy Anchor Link

🎉Tutorial completeYou can now build CRUD APIs, return honest HTTP errors, understand the request pipeline, and read NextRush code. Every bigger app is this same shape — more middleware, more routes, same pipeline.

Continue learningCopy Anchor Link

One recommended path, then depth when you need it: