create-api

Create API Endpoint

Scaffold a production-ready API endpoint for: $ARGUMENTS

Step 0 — Auto-Branch (if on main)

Before creating any files, check the current branch:

git branch --show-current

Default behavior (auto_branch = true in claude-mastery-project.conf):

• If on main or master: automatically create a feature branch and switch to it:

  git checkout -b feat/api-<resource-name>
  

  Report: "Created branch feat/api-<resource> — main stays untouched."
• If already on a feature branch: proceed
• If not a git repo: skip this check

To disable: Set auto_branch = false in claude-mastery-project.conf. When disabled, warn and ask the user before proceeding on main.

Step 1 — Gather Context

Before scaffolding, read the current project:

1. Read src/server.ts (or src/server.js, src/index.ts) — understand the server setup
2. Scan src/routes/ — check for existing route patterns to follow
3. Scan src/handlers/ — check for existing handler patterns
4. Scan src/types/ — check for existing type patterns
5. Read .env.example — check for database config

If --no-db is in the arguments, skip database integration. Otherwise, use StrictDB if it's installed, or the native MongoDB driver if not (always through the adapter, never Mongoose).

Step 2 — Create Files

Generate these files for the resource:

File 1: src/types/<resource>.ts — Types first (they're the spec)

/** Database document shape */
export interface <Resource>Doc {
  _id: string;
  // Add fields based on the resource
  createdAt: Date;
  updatedAt: Date;
}

/** API request body for creating a resource */
export interface Create<Resource>Body {
  // Fields the client sends (NO _id, NO timestamps)
}

/** API request body for updating a resource */
export interface Update<Resource>Body {
  // Partial fields the client can update
}

/** API response shape (what the client receives) */
export interface <Resource>Response {
  id: string;
  // Mapped from the doc — NEVER expose _id directly
  createdAt: string;
  updatedAt: string;
}