🏁 Weekend Project: A Polyglot Mini-Server

The Brief

Your client (you) needs a small backend service to manage a to-do list. It must store tasks, let a client create/read/update/delete them, and behave like a proper REST API — correct verbs, correct status codes, sensible errors. Simple on the surface, but it exercises every core skill from this module.

To keep the focus on architecture rather than tooling, storage stays in memory (a plain array/list) for now. That's a deliberate constraint: a database is a later module, and building without one first makes the boundary between "web layer" and "data layer" obvious.

💡 Why build it three times? A skill you can only perform in one framework is a framework skill. A skill you can reproduce in three is an architecture skill. By the third implementation you'll stop thinking "how do I do routing in Flask?" and start thinking "where does routing belong?" — that's the whole goal.

Design the Architecture First

Before a single line of code, sketch the layers. Every one of your three servers will fill these same boxes; only the syntax changes.

Notice each layer has a single job:

• Routing — inspects the HTTP method and URL, then dispatches to the right handler. It knows nothing about tasks.
• Handlers (controllers) — validate input, decide the correct status code, and call the data store. This is where your business rules live.
• Data store — the only code that reads or writes the task list. Swap this out later for a database and nothing else needs to change.

The API Contract

All three servers must honour the same contract. Design it now and treat it as the source of truth — your tests will check it, and any client should work against any of your three servers unchanged.

The task resource looks like this:

{
  "id": 1,
  "title": "Learn RESTful APIs",
  "completed": false
}

Milestones & Timeline

Break the weekend into five milestones. Finish each one — including its test — before moving on. Working in small, verified steps is the single biggest predictor of finishing.

💡 Do M2 thoroughly. Your first implementation is where you actually design the handlers and error cases. M3 and M4 are mostly translation — they go fast because M2 did the thinking.

Guided Build (Three Ways)

Below is a reference implementation of each server. Read them, but type them yourself — muscle memory matters. Each keeps the three layers visible even in a single file.

Milestone 2 — Node.js (Express)

Express gives you routing and JSON body parsing out of the box. Install it first:

mkdir task-api-node && cd task-api-node
npm init -y
npm install express

// server.js — Task API (Node.js + Express)
const express = require('express');
const app = express();
app.use(express.json()); // parse JSON request bodies

// --- Data store layer (swap for a DB later) ---
let tasks = [{ id: 1, title: 'Learn RESTful APIs', completed: false }];
let nextId = 2;

// --- Handler layer ---
// GET /tasks — list all
app.get('/tasks', (req, res) => {
  res.status(200).json(tasks);
});

// GET /tasks/:id — one task
app.get('/tasks/:id', (req, res) => {
  const task = tasks.find(t => t.id === Number(req.params.id));
  if (!task) return res.status(404).json({ error: 'Task not found' });
  res.status(200).json(task);
});

// POST /tasks — create
app.post('/tasks', (req, res) => {
  const { title, completed = false } = req.body;
  if (!title) return res.status(400).json({ error: 'title is required' });
  const task = { id: nextId++, title, completed: Boolean(completed) };
  tasks.push(task);
  res.status(201).json(task);
});

// PUT /tasks/:id — update
app.put('/tasks/:id', (req, res) => {
  const task = tasks.find(t => t.id === Number(req.params.id));
  if (!task) return res.status(404).json({ error: 'Task not found' });
  if (req.body.title !== undefined) task.title = req.body.title;
  if (req.body.completed !== undefined) task.completed = Boolean(req.body.completed);
  res.status(200).json(task);
});

// DELETE /tasks/:id — remove
app.delete('/tasks/:id', (req, res) => {
  const index = tasks.findIndex(t => t.id === Number(req.params.id));
  if (index === -1) return res.status(404).json({ error: 'Task not found' });
  tasks.splice(index, 1);
  res.status(204).end();
});

app.listen(3000, () => console.log('Node API on http://localhost:3000'));

node server.js
# → Node API on http://localhost:3000

Milestone 3 — Python (Flask)

Flask's decorators are the routing layer. Install and run inside a virtual environment:

python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate
pip install flask

# app.py — Task API (Python + Flask)
from flask import Flask, request, jsonify

app = Flask(__name__)

# --- Data store layer ---
tasks = [{"id": 1, "title": "Learn RESTful APIs", "completed": False}]
next_id = 2

def find_task(task_id):
    return next((t for t in tasks if t["id"] == task_id), None)

# --- Handler layer ---
@app.get("/tasks")
def list_tasks():
    return jsonify(tasks), 200

@app.get("/tasks/")
def get_task(task_id):
    task = find_task(task_id)
    if task is None:
        return jsonify(error="Task not found"), 404
    return jsonify(task), 200

@app.post("/tasks")
def create_task():
    global next_id
    data = request.get_json(silent=True) or {}
    if not data.get("title"):
        return jsonify(error="title is required"), 400
    task = {"id": next_id, "title": data["title"],
            "completed": bool(data.get("completed", False))}
    next_id += 1
    tasks.append(task)
    return jsonify(task), 201

@app.put("/tasks/")
def update_task(task_id):
    task = find_task(task_id)
    if task is None:
        return jsonify(error="Task not found"), 404
    data = request.get_json(silent=True) or {}
    if "title" in data:
        task["title"] = data["title"]
    if "completed" in data:
        task["completed"] = bool(data["completed"])
    return jsonify(task), 200

@app.delete("/tasks/")
def delete_task(task_id):
    task = find_task(task_id)
    if task is None:
        return jsonify(error="Task not found"), 404
    tasks.remove(task)
    return "", 204

if __name__ == "__main__":
    app.run(port=5000, debug=True)

python app.py
# → Running on http://localhost:5000

Milestone 4 — PHP

Plain PHP has no built-in router, so you write a tiny one — which makes the routing layer wonderfully explicit. No dependencies needed; use PHP's built-in server.

<?php
// index.php — Task API (plain PHP)
header('Content-Type: application/json');

// --- Data store layer (in-memory per request; see note below) ---
session_start();
if (!isset($_SESSION['tasks'])) {
    $_SESSION['tasks'] = [['id' => 1, 'title' => 'Learn RESTful APIs', 'completed' => false]];
    $_SESSION['nextId'] = 2;
}

function &store() { return $_SESSION['tasks']; }

function find_task($id) {
    foreach ($_SESSION['tasks'] as $i => $t) {
        if ($t['id'] === (int)$id) return $i;
    }
    return -1;
}

function send($data, $code = 200) {
    http_response_code($code);
    if ($data !== null) echo json_encode($data);
    exit;
}

// --- Routing layer ---
$method = $_SERVER['REQUEST_METHOD'];
$path   = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$body   = json_decode(file_get_contents('php://input'), true) ?? [];

// --- Handler layer ---
if (preg_match('#^/tasks/(\d+)$#', $path, $m)) {
    $id = (int)$m[1];
    $index = find_task($id);

    if ($method === 'GET') {
        $index === -1 ? send(['error' => 'Task not found'], 404)
                      : send($_SESSION['tasks'][$index]);
    }
    if ($method === 'PUT') {
        if ($index === -1) send(['error' => 'Task not found'], 404);
        if (isset($body['title']))     $_SESSION['tasks'][$index]['title'] = $body['title'];
        if (isset($body['completed'])) $_SESSION['tasks'][$index]['completed'] = (bool)$body['completed'];
        send($_SESSION['tasks'][$index]);
    }
    if ($method === 'DELETE') {
        if ($index === -1) send(['error' => 'Task not found'], 404);
        array_splice($_SESSION['tasks'], $index, 1);
        send(null, 204);
    }
}

if ($path === '/tasks') {
    if ($method === 'GET') {
        send(array_values($_SESSION['tasks']));
    }
    if ($method === 'POST') {
        if (empty($body['title'])) send(['error' => 'title is required'], 400);
        $task = ['id' => $_SESSION['nextId']++, 'title' => $body['title'],
                 'completed' => (bool)($body['completed'] ?? false)];
        $_SESSION['tasks'][] = $task;
        send($task, 201);
    }
}

send(['error' => 'Not found'], 404);

php -S localhost:8000
# serves index.php at http://localhost:8000

Testing Your API

Don't eyeball it — hit every endpoint. These curl commands form your acceptance test; run the same set against all three servers, changing only the port (Node 3000, Flask 5000, PHP 8000).

# Create a task → expect 201 + the new task
curl -i -X POST http://localhost:3000/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Write tests", "completed": false}'

# List all tasks → expect 200 + array
curl -i http://localhost:3000/tasks

# Get one → expect 200; get a missing one → expect 404
curl -i http://localhost:3000/tasks/1
curl -i http://localhost:3000/tasks/999

# Update → expect 200 + updated task
curl -i -X PUT http://localhost:3000/tasks/1 \
  -H "Content-Type: application/json" \
  -d '{"completed": true}'

# Delete → expect 204 (no body)
curl -i -X DELETE http://localhost:3000/tasks/1

# Bad create (no title) → expect 400
curl -i -X POST http://localhost:3000/tasks \
  -H "Content-Type: application/json" -d '{}'

Prefer a GUI? Import the same requests into Postman or Insomnia as a collection so you can re-run the whole suite against each server with one click.

Completion Checklist

You're done when every box is ticked for all three servers. Print this or copy it into your project README.

What Good Looks Like

Anyone can make endpoints return something. Here's how to tell a solid submission from a shaky one — use it to grade yourself honestly.

Summary & Quiz

📚 Further Reading

• Express.js — Routing Guide
• Flask — Quickstart
• PHP — Built-in Web Server
• RESTful API Design Guidelines
• MDN — HTTP Status Codes

🚀 What's Next?

Your data store is the last hand-rolled piece. In the next module we replace that in-memory array with a real database — starting with the concepts and types of databases you'll choose between.