pn-node-api

Node / API skill

When to use

• Designing or implementing REST/API endpoints.
• Adding or changing database access (queries, migrations, connections).
• Setting up or refactoring env/config and secrets.
• Reviewing backend error handling and safety.
• Establishing consistent request/response patterns across an API.

Workflow

1. API design

Use clear resource names (nouns), appropriate HTTP methods, and standard status codes. Design the contract before writing implementation.

// Resource: /users
// Collection:  GET /users, POST /users
// Resource:    GET /users/:id, PATCH /users/:id, HTTP DELETE on /users/:id
// Sub-resource: GET /users/:id/orders

// Status codes — always be specific
// 201 Created (POST that creates a resource)
// 204 No Content (DELETE or PATCH with no body to return)
// 400 Bad Request (malformed syntax, wrong types)
// 401 Unauthorized (no valid credentials)
// 403 Forbidden (valid credentials, wrong permissions)
// 404 Not Found (resource doesn't exist)
// 422 Unprocessable (valid JSON, failed business rules / validation)
// 429 Too Many Requests (rate limited)
// 500 Internal Server Error (unexpected programmer error)

Document request/response shapes with OpenAPI or TypeScript interfaces before implementation. Reference pn-core://skills/backend/reference/api-design.md for full REST conventions, versioning, pagination, and anti-patterns.

2. Input validation

Validate at the route boundary — before any business logic executes.

import { z } from "zod";

export const CreateUserSchema = z.object({
  email: z.string().email().max(255).toLowerCase(),
  name: z.string().min(1).max(100).trim(),
  role: z.enum(["user", "admin"]).default("user"),
});

// In the route handler
const result = CreateUserSchema.safeParse(req.body);
if (!result.success) {
  throw new AppError("VALIDATION_FAILED", 422, "Invalid request data");
}
const validated = result.data; // TypeScript knows the shape

3. Config and secrets