{
  "id": "page:docs-user-guide-tutorials-beginner-rest-api",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/tutorials/beginner-rest-api.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/tutorials/beginner-rest-api.md",
    "sourceKind": "repo-docs",
    "title": "Beginner Tutorial: Build a Simple REST API with TDD",
    "displayName": "Beginner Tutorial: Build a Simple REST API with TDD",
    "slug": "docs/user-guide/tutorials/beginner-rest-api",
    "articlePath": "wiki/docs/user-guide/tutorials/beginner-rest-api.md",
    "article": "\n# Beginner Tutorial: Build a Simple REST API with TDD\n\n**Version:** 1.0\n**Date:** 2026-01-25\n**Category:** Tutorial\n**Level:** Beginner\n**Estimated Time:** 45-60 minutes\n**Primary Personas:** James Park (Curious Newcomer), Sarah Chen (onboarding)\n\n---\n\n## Learning Objectives\n\nBy the end of this tutorial, you will be able to:\n\n1. **Start a Babysitter workflow** using natural language commands\n2. **Understand the TDD (Test-Driven Development) process** as orchestrated by Babysitter\n3. **Observe quality convergence** as Babysitter iterates toward your quality target\n4. **Interpret run output** including the journal, artifacts, and quality scores\n5. **Resume an interrupted workflow** if your session ends unexpectedly\n\n---\n\n## Prerequisites\n\nBefore starting this tutorial, please ensure you have:\n\n- [ ] **Node.js v20+** installed ([download here](https://nodejs.org/))\n- [ ] **Claude Code** installed and configured ([setup guide](https://code.claude.com/docs))\n- [ ] **Babysitter SDK and plugin** installed (see [Installation Guide](../getting-started/installation.md))\n- [ ] A **new empty project directory** for this tutorial\n- [ ] Basic familiarity with **JavaScript** and **REST APIs**\n\n### Verify Your Installation\n\nBefore we begin, let's verify everything is set up correctly. Open your terminal and run these commands:\n\n```bash\n# Check Node.js version (should be 20+)\nnode --version\n\n# Check if Babysitter SDK is installed\nbabysitter --version\n```\n\n**What you should see:**\n\nFor the Node.js check:\n```\nv20.x.x or higher\n```\n\n### About Breakpoints\n\nBabysitter has two modes for handling breakpoints (approval prompts):\n\n1. **Interactive Mode (Claude Code)**: When running in Claude Code, breakpoints are handled directly in the chat - Claude asks you questions and you respond. **No setup required!**\n\n2. **Non-Interactive Mode**: For CI/CD or headless automation, breakpoints are disabled.\n\n**For this tutorial, we'll use interactive mode** - just respond to Claude's questions in the chat. No additional service needed!\n\n---\n\n## What We're Building\n\nIn this tutorial, we will build a simple **Task Manager REST API** with the following features:\n\n- **GET /tasks** - Retrieve all tasks\n- **POST /tasks** - Create a new task\n- **GET /tasks/:id** - Retrieve a specific task\n- **PUT /tasks/:id** - Update a task\n- **DELETE /tasks/:id** - Delete a task\n\nWe will use **Express.js** as our web framework and **in-memory storage** (no database needed for this tutorial). Babysitter will guide us through a TDD approach, writing tests first and then implementing the code to pass those tests.\n\n### Why TDD with Babysitter?\n\nTest-Driven Development ensures your code works correctly from the start. Babysitter makes TDD easier by:\n\n1. **Writing tests first** based on your requirements\n2. **Implementing code** to pass those tests\n3. **Iterating automatically** until quality targets are met\n4. **Tracking everything** in an auditable journal\n\nThis means you get high-quality, well-tested code without manually managing the iteration cycle.\n\n---\n\n## Step 1: Set Up Your Project Directory\n\nLet's start by creating a fresh project for our API. We will do this manually to ensure we understand the foundation.\n\nOpen your terminal and run:\n\n```bash\n# Create and navigate to your project directory\nmkdir task-api-tutorial\ncd task-api-tutorial\n\n# Initialize a new Node.js project\nnpm init -y\n\n# Install Express.js and testing dependencies\nnpm install express\nnpm install --save-dev jest supertest\n```\n\n**What you should see:**\n\nAfter `npm init -y`:\n```json\n{\n  \"name\": \"task-api-tutorial\",\n  \"version\": \"1.0.0\",\n  ...\n}\n```\n\nAfter installing dependencies:\n```\nadded X packages in Ys\n```\n\nNow let's configure Jest for testing. Open `package.json` and update the \"scripts\" section:\n\n```json\n{\n  \"scripts\": {\n    \"test\": \"jest\",\n    \"test:watch\": \"jest --watch\"\n  }\n}\n```\n\n**Checkpoint 1:** Your project directory should now contain:\n- `package.json` (with Express, Jest, and Supertest listed)\n- `node_modules/` directory\n- `package-lock.json`\n\n---\n\n## Step 2: Start Claude Code in Your Project\n\nNow we're ready to use Babysitter. Open Claude Code in your project directory:\n\n```bash\nclaude\n```\n\n**What you should see:**\n\nClaude Code will start and show you its prompt. You're now ready to interact with Claude and use the Babysitter skill.\n\n> **Note:** Make sure you're in your `task-api-tutorial` directory when you start Claude Code. Babysitter will create its workflow files relative to your current directory.\n\n---\n\n## Step 3: Start Your First Babysitter Run\n\nNow comes the exciting part! We will ask Claude to use the Babysitter skill to build our REST API with TDD.\n\nIn Claude Code, type:\n\n```\n/babysitter:call Build a REST API for task management with Express.js. Include:\n- GET /tasks to list all tasks\n- POST /tasks to create a task (with title and completed status)\n- GET /tasks/:id to get a specific task\n- PUT /tasks/:id to update a task\n- DELETE /tasks/:id to delete a task\nUse TDD with 80% quality target and max 5 iterations.\n```\n\nAlternatively, you can use natural language:\n\n```\nUse the babysitter skill to build a REST API for task management with Express.js.\nInclude CRUD operations for tasks (title and completed status).\nUse TDD methodology with an 80% quality target and maximum 5 iterations.\n```\n\n**What you should see:**\n\nBabysitter will acknowledge your request and create a new run:\n\n```\nCreating new babysitter run: task-api-20260125-143012\n\nProcess Definition: TDD Quality Convergence\nTarget Quality: 80%\nMax Iterations: 5\n\nRun ID: 01KFFTSF8TK8C9GT3YM9QYQ6WG\nRun Directory: .a5c/runs/01KFFTSF8TK8C9GT3YM9QYQ6WG/\n```\n\n> **Understanding the Output:**\n> - **Run ID**: A unique identifier for this workflow run\n> - **Run Directory**: Where Babysitter stores all artifacts and logs\n> - **Target Quality**: The minimum quality score to achieve (80/100)\n> - **Max Iterations**: How many times Babysitter will try to improve\n\n---\n\n## Step 4: Observe the Research Phase\n\nAfter starting the run, Babysitter enters the **Research Phase**. During this phase, it analyzes your project and requirements to understand the context.\n\n**What you should see:**\n\n```\n[Iteration 1/5] Starting research phase...\n\nTask: Research Codebase Patterns\n- Analyzing project structure... Done\n- Checking for existing Express patterns... Done\n- Reviewing package.json dependencies... Done\n- Identifying test framework (Jest)... Done\n\nResearch Summary:\n- Fresh Express.js project\n- Jest configured for testing\n- No existing routes or models\n- Supertest available for API testing\n```\n\nThis phase is important because it helps Babysitter understand your project's context and make appropriate decisions about how to structure the code.\n\n**Checkpoint 2:** You should see the research phase complete with a summary of your project.\n\n---\n\n## Step 5: Review the Specifications Phase\n\nNext, Babysitter generates detailed **Specifications** based on your requirements and research.\n\n**What you should see:**\n\n```\nTask: Generate Specifications\nCreating detailed specs for task management API...\n\nSpecifications:\n- Endpoints: GET /tasks, POST /tasks, GET /tasks/:id, PUT /tasks/:id, DELETE /tasks/:id\n- Data Model: Task { id: string, title: string, completed: boolean, createdAt: Date }\n- Storage: In-memory array (no database)\n- Validation: Title required, completed defaults to false\n- Error Handling: 404 for not found, 400 for validation errors\n\nTest Plan:\n- Unit tests for task validation\n- Integration tests for each endpoint\n- Edge case tests (empty list, invalid ID, missing fields)\n```\n\nAt this point, you might see a **breakpoint** requesting your approval of the specifications.\n\n---\n\n## Step 6: Approve the Specifications (Breakpoint)\n\nBabysitter uses **breakpoints** to get human approval at critical decision points. This ensures you stay in control of important decisions.\n\n### Interactive Mode (Claude Code) - What You'll See:\n\nSince you're running in Claude Code, Claude will ask you directly in the chat:\n\n```\nClaude: The specification phase is complete. Here's what I've planned:\n\n        Specifications:\n        - 5 CRUD endpoints defined\n        - In-memory storage (no database setup)\n        - Jest + Supertest for testing\n        - Basic validation rules\n\n        Do you approve these specifications to proceed with implementation?\n\n        [Approve] [Reject] [Request Changes]\n\nYou: [Click Approve or type \"yes\"]\n\nClaude: Specifications approved. Proceeding with TDD implementation...\n```\n\nSimply respond to Claude's question to continue!\n\n### Non-Interactive Mode (Alternative):\n\nIf you were running in non-interactive mode (CI/CD, scripts), you would instead see:\n\n```\nWaiting for breakpoint approval...\nVisit http://localhost:3184 to approve or reject.\n```\n\nAnd you'd approve via the web UI at `http://localhost:3184`.\n\n> **Why Breakpoints Matter:**\n> Breakpoints create a human-in-the-loop workflow. This means:\n> - You maintain control over important decisions\n> - Every approval is logged for audit trails\n> - You can reject and provide feedback if something isn't right\n\n**Checkpoint 3:** You should have successfully approved the specifications breakpoint (via chat or web UI).\n\n---\n\n## Step 7: Watch the TDD Implementation Loop\n\nNow Babysitter enters the core **TDD Implementation Loop**. This is where the magic happens!\n\n### Iteration 1: First Pass\n\n**What you should see:**\n\n```\n[Iteration 1/5] Starting TDD implementation...\n\nTask: Write Tests First\n- Writing endpoint integration tests... Done (12 test cases)\n- Writing validation tests... Done (5 test cases)\n- Writing edge case tests... Done (4 test cases)\n\nTask: Implement Code\n- Creating task model... Done\n- Implementing routes... Done\n- Adding validation middleware... Done\n- Setting up Express app... Done\n\nRunning Quality Checks...\n- Coverage: 68% (target: 80%)\n- ESLint: 2 warnings\n- Tests: 19/21 passing (2 failures)\n\nAgent Quality Score: 62/100 (below target)\nIssues identified:\n- Coverage below threshold (68% < 80%)\n- 2 failing tests in edge cases\n- Minor ESLint warnings\n\nContinuing to next iteration...\n```\n\nDon't worry that the first iteration didn't meet the target - this is expected! Babysitter will now iterate to fix the issues.\n\n### Iteration 2: Refinement\n\n**What you should see:**\n\n```\n[Iteration 2/5] Refining implementation...\n\nTask: Fix Failing Tests\n- Fixed test for empty task title... Done\n- Fixed test for invalid task ID format... Done\n\nTask: Improve Coverage\n- Added tests for error handling paths... Done\n- Added tests for edge cases in DELETE... Done\n\nTask: Fix ESLint Issues\n- Fixed unused variable warning... Done\n- Applied consistent code style... Done\n\nRunning Quality Checks...\n- Coverage: 84% (target: 80%)\n- ESLint: 0 warnings\n- Tests: 21/21 passing\n\nAgent Quality Score: 88/100 (target met!)\n\nQuality target achieved in 2 iterations!\n```\n\n**Checkpoint 4:** The workflow should achieve the quality target (likely in 2-3 iterations).\n\n---\n\n## Step 8: Review the Created Files\n\nNow let's examine what Babysitter created. Your project should have new files:\n\n```bash\n# List the created files\nls -la\n```\n\n**Expected file structure:**\n\n```\ntask-api-tutorial/\n  node_modules/\n  .a5c/\n    runs/\n      01KFFTSF8TK8C9GT3YM9QYQ6WG/\n        journal/\n          journal.jsonl\n        state.json\n        tasks/\n  src/\n    app.js           # Express application setup\n    routes/\n      tasks.js       # Task routes\n    models/\n      task.js        # Task model and storage\n    middleware/\n      validation.js  # Input validation\n  tests/\n    tasks.test.js    # Integration tests\n  package.json\n```\n\nLet's look at some of the created code:\n\n### The Task Model (`src/models/task.js`)\n\n```javascript\n// This is an example of what Babysitter might generate\nconst tasks = [];\n\nconst Task = {\n  findAll: () => tasks,\n  findById: (id) => tasks.find(t => t.id === id),\n  create: (data) => {\n    const task = {\n      id: Date.now().toString(),\n      title: data.title,\n      completed: data.completed || false,\n      createdAt: new Date()\n    };\n    tasks.push(task);\n    return task;\n  },\n  update: (id, data) => {\n    const index = tasks.findIndex(t => t.id === id);\n    if (index === -1) return null;\n    tasks[index] = { ...tasks[index], ...data };\n    return tasks[index];\n  },\n  delete: (id) => {\n    const index = tasks.findIndex(t => t.id === id);\n    if (index === -1) return false;\n    tasks.splice(index, 1);\n    return true;\n  }\n};\n\nmodule.exports = Task;\n```\n\n### A Test File (`tests/tasks.test.js`)\n\n```javascript\n// Example of generated test structure\nconst request = require('supertest');\nconst app = require('../src/app');\n\ndescribe('Tasks API', () => {\n  describe('GET /tasks', () => {\n    it('should return an empty array initially', async () => {\n      const res = await request(app).get('/tasks');\n      expect(res.status).toBe(200);\n      expect(res.body).toEqual([]);\n    });\n  });\n\n  describe('POST /tasks', () => {\n    it('should create a new task', async () => {\n      const res = await request(app)\n        .post('/tasks')\n        .send({ title: 'Test Task' });\n      expect(res.status).toBe(201);\n      expect(res.body).toHaveProperty('id');\n      expect(res.body.title).toBe('Test Task');\n    });\n\n    it('should return 400 if title is missing', async () => {\n      const res = await request(app)\n        .post('/tasks')\n        .send({});\n      expect(res.status).toBe(400);\n    });\n  });\n\n  // More tests...\n});\n```\n\n---\n\n## Step 9: Run the Tests Yourself\n\nLet's verify that everything works by running the tests manually:\n\n```bash\nnpm test\n```\n\n**What you should see:**\n\n```\nPASS  tests/tasks.test.js\n  Tasks API\n    GET /tasks\n      - should return an empty array initially (23 ms)\n      - should return all tasks after creation (18 ms)\n    POST /tasks\n      - should create a new task (15 ms)\n      - should return 400 if title is missing (12 ms)\n    GET /tasks/:id\n      - should return a specific task (14 ms)\n      - should return 404 for non-existent task (11 ms)\n    PUT /tasks/:id\n      - should update a task (16 ms)\n      - should return 404 for non-existent task (10 ms)\n    DELETE /tasks/:id\n      - should delete a task (13 ms)\n      - should return 404 for non-existent task (9 ms)\n\nTest Suites: 1 passed, 1 total\nTests:       21 passed, 21 total\n```\n\n**Checkpoint 5:** All tests should pass when you run `npm test`.\n\n---\n\n## Step 10: Explore the Journal\n\nOne of Babysitter's most powerful features is its **event-sourced journal**. This provides a complete audit trail of everything that happened during the run.\n\nLet's examine it:\n\n```bash\n# View the journal (replace with your actual run ID)\ncat .a5c/runs/01KFFTSF8TK8C9GT3YM9QYQ6WG/journal/journal.jsonl | head -20\n```\n\n**What you should see:**\n\n```json\n{\"type\":\"RUN_STARTED\",\"timestamp\":\"2026-01-25T14:30:12.445Z\",\"runId\":\"01KFFTSF8TK8C9GT3YM9QYQ6WG\",\"inputs\":{...}}\n{\"type\":\"ITERATION_STARTED\",\"timestamp\":\"2026-01-25T14:30:12.567Z\",\"iteration\":1}\n{\"type\":\"TASK_STARTED\",\"timestamp\":\"2026-01-25T14:30:13.123Z\",\"taskId\":\"research-001\",\"taskType\":\"agent\"}\n{\"type\":\"TASK_COMPLETED\",\"timestamp\":\"2026-01-25T14:30:45.789Z\",\"taskId\":\"research-001\",\"result\":{\"status\":\"success\"}}\n{\"type\":\"TASK_STARTED\",\"timestamp\":\"2026-01-25T14:30:46.001Z\",\"taskId\":\"specs-001\",\"taskType\":\"agent\"}\n...\n{\"type\":\"BREAKPOINT_REQUESTED\",\"timestamp\":\"2026-01-25T14:31:12.234Z\",\"breakpointId\":\"bp-001\",\"question\":\"Review and approve specifications?\"}\n{\"type\":\"BREAKPOINT_APPROVED\",\"timestamp\":\"2026-01-25T14:31:45.123Z\",\"breakpointId\":\"bp-001\"}\n...\n{\"type\":\"QUALITY_SCORE\",\"timestamp\":\"2026-01-25T14:33:23.456Z\",\"iteration\":1,\"score\":62}\n{\"type\":\"QUALITY_SCORE\",\"timestamp\":\"2026-01-25T14:34:44.789Z\",\"iteration\":2,\"score\":88}\n{\"type\":\"RUN_COMPLETED\",\"timestamp\":\"2026-01-25T14:34:44.890Z\",\"status\":\"success\"}\n```\n\n> **Why the Journal Matters:**\n> - **Audit Trail:** Complete record of all decisions and actions\n> - **Debugging:** Understand exactly what happened if something goes wrong\n> - **Resumability:** Babysitter can resume from any point using this journal\n> - **Compliance:** Proof of human approvals and quality checks\n\n---\n\n## Step 11: Start the API Server (Optional)\n\nLet's verify our API works by starting the server:\n\n```bash\n# Start the server (you may need to add a start script)\nnode src/app.js\n```\n\nOr add a start script to `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"start\": \"node src/app.js\",\n    \"test\": \"jest\"\n  }\n}\n```\n\nThen run:\n\n```bash\nnpm start\n```\n\n**What you should see:**\n\n```\nTask API server running on port 3000\n```\n\nNow you can test the API with curl:\n\n```bash\n# Create a task\ncurl -X POST http://localhost:3000/tasks \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"title\": \"Learn Babysitter\"}'\n\n# List all tasks\ncurl http://localhost:3000/tasks\n```\n\n---\n\n## Step 12: Simulate Session Interruption and Resume\n\nLet's learn how to handle session interruptions. This is crucial for real-world use where you might close your laptop, lose network connection, or need to continue work the next day.\n\n### Simulating Interruption\n\nIf you were to close Claude Code mid-run (please don't do this for a completed run), you could resume it later.\n\n### Resuming a Run\n\nTo resume a previously interrupted run, you would use:\n\n```\n/babysitter:call resume --run-id 01KFFTSF8TK8C9GT3YM9QYQ6WG\n```\n\nOr in natural language:\n\n```\nResume the babysitter run 01KFFTSF8TK8C9GT3YM9QYQ6WG\n```\n\n**What would happen:**\n\n```\nResuming run: 01KFFTSF8TK8C9GT3YM9QYQ6WG\n\nReplaying journal...\n- Found 47 events\n- Last completed task: implement-002\n- Resuming from iteration 2\n\nContinuing workflow...\n```\n\n> **Key Insight:** Because Babysitter uses event sourcing, all progress is preserved. You never lose work due to session interruptions.\n\n---\n\n## Summary\n\nCongratulations! You have successfully completed your first Babysitter tutorial. Let's review what you accomplished:\n\n### What You Built\n- A fully functional REST API with 5 endpoints\n- Comprehensive test suite with 21 tests\n- 80%+ code coverage\n- Clean, well-structured code\n\n### What You Learned\n\n1. **Starting a Babysitter workflow** with the `/babysit` command\n2. **Understanding the phases**: Research, Specifications, TDD Implementation\n3. **Using breakpoints** for human-in-the-loop approval\n4. **Observing quality convergence** as Babysitter iterates to meet targets\n5. **Reading the journal** to understand what happened\n6. **Resuming interrupted runs** to continue work later\n\n### Key Concepts\n\n| Concept | What It Means |\n|---------|---------------|\n| **TDD Quality Convergence** | Writing tests first, then implementing code, iterating until quality target is met |\n| **Breakpoints** | Human approval gates for critical decisions |\n| **Journal** | Event-sourced audit trail of all actions |\n| **Quality Score** | Automated assessment of code quality (tests, coverage, linting) |\n| **Iteration** | One pass through the implementation and quality check cycle |\n\n---\n\n## Next Steps\n\nNow that you've completed the beginner tutorial, here are some paths to continue your learning:\n\n### Continue Learning\n- **[Intermediate Tutorial: Custom Process Definition](./intermediate-custom-process.md)** - Learn to create custom workflows with parallel execution and approval gates\n- **[Advanced Tutorial: Multi-Phase Feature Development](./advanced-multi-phase.md)** - Master complex team workflows with quality convergence\n\n### Go Deeper\n- **[Event Sourcing Explained](../features/journal-system.md)** - Understand the architecture behind Babysitter\n- **[Quality Convergence Explained](../features/quality-convergence.md)** - Learn how quality scoring works\n\n### Apply Your Knowledge\n- **[Quality Convergence](../features/quality-convergence.md)** - Fine-tune quality settings for your projects\n- **[Breakpoints](../features/breakpoints.md)** - Customize approval workflows\n\n---\n\n## Troubleshooting\n\n### Issue: \"Plugin not found: babysitter@a5c.ai\"\n\n**Symptom:** Claude Code doesn't recognize the babysitter command.\n\n**Solution:**\n```bash\n# Reinstall the plugin\nclaude plugin marketplace add a5c-ai/babysitter-claude\nclaude plugin install --scope user babysitter@a5c.ai\nclaude plugin enable --scope user babysitter@a5c.ai\n\n# Restart Claude Code\n```\n\n### Issue: \"Breakpoint not resolving\"\n\n**Symptom:** Workflow is waiting for breakpoint approval but nothing happens.\n\n**Solution (Interactive Mode - Claude Code):**\n1. Look for Claude's question in the chat - scroll up if needed\n2. Respond to the question to continue\n3. If the session timed out, resume with `/babysitter:call resume`\n\n**Solution (Non-Interactive Mode):**\n1. Breakpoints are disabled in non-interactive mode\n\n### Issue: \"Quality target never reached\"\n\n**Symptom:** Babysitter keeps iterating but the quality score doesn't improve.\n\n**Solution:**\n1. Check the iteration logs for specific issues\n2. Consider lowering your quality target (e.g., 75% instead of 80%)\n3. Review failing tests manually and provide feedback to Claude\n\n### Issue: \"Tests failing after run completion\"\n\n**Symptom:** Running `npm test` shows failures even though Babysitter reported success.\n\n**Solution:**\n1. This can happen if there are environmental differences\n2. Check if all dependencies are installed: `npm install`\n3. Ensure you're in the correct directory\n4. Review the test files for any environment-specific configurations\n\n---\n\n## See Also\n\n- [Glossary](../reference/glossary.md) - Definitions of all Babysitter terms\n- [CLI Reference](../reference/cli-reference.md) - Complete command reference\n- [Getting Started](../getting-started/first-run.md) - Conceptual overview\n\n---\n\n**Document Status:** Complete\n**Last Updated:** 2026-01-25\n**Feedback:** Found an issue? [Report it on GitHub](https://github.com/a5c-ai/babysitter/issues)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide-tutorials",
      "to": "page:docs-user-guide-tutorials-beginner-rest-api",
      "kind": "contains_page"
    }
  ]
}