write-api-route

Writing ryOS API Routes

ryOS API routes are Node-style handlers under api/, served by the standalone Bun server (scripts/api-standalone-server.ts). The canonical reference is docs/8.10-api-design-guide.md — read it for the full contract. This skill is the practical checklist.

Quick Start Checklist

- [ ] 1. Pick the path: api/<feature>/index.ts (collection) or api/<feature>/[id].ts (item)
- [ ] 2. Wrap the handler in apiHandler({ methods, auth, ... })
- [ ] 3. Validate input (Zod via bodySchema, or _utils/_validation.ts helpers)
- [ ] 4. Rate-limit public / expensive routes (_utils/_rate-limit.ts)
- [ ] 5. Use shared constants/keys (_utils/constants.ts, REDIS_PREFIXES)
- [ ] 6. Return explicit JSON; errors as { error: "..." }
- [ ] 7. Add structured logs (logger.info / branch decisions)
- [ ] 8. Write/extend an integration test in tests/ (requires `bun run dev:api`)
- [ ] 9. Update the matching docs/8.*.md if the contract changed

File & Naming Conventions

api/
├── _utils/                 # globally shared helpers (api-handler, redis, request-auth, ...)
├── <feature>/
│   ├── index.ts            # collection route (GET list / POST create)
│   ├── [id].ts             # item route (path param :id)
│   ├── [id]/messages.ts    # nested dynamic routes
│   └── _helpers/           # feature-private helpers (_constants.ts, _types.ts, ...)

• _utils/ = global utilities; feature _helpers/ = domain-specific internals.
• _*.ts / _helpers/ are private modules (not routes).
• Use index.ts for collections, [id].ts and nested folders for path params.
• Import shared modules with the .js extension (e.g. from "../_utils/api-handler.js") — required for Node-style ESM resolution even though the source is .ts.

Primary Pattern: apiHandler

Prefer apiHandler for all new JSON endpoints. It centralizes CORS/preflight, origin allowlisting, method checks, Redis injection, auth resolution, body parsing/validation, analytics, and a 500 fallback.

import { apiHandler } from "../_utils/api-handler.js";
import { z } from "zod";

const bodySchema = z.object({
  name: z.string().min(1).max(100),
});

export default apiHandler(
  {
    methods: ["POST"],
    auth: "required",        // "none" | "optional" | "required" | "admin"
    parseJsonBody: true,     // implied when bodySchema is set
    bodySchema,              // 400 { error: "validation_error", issues } on failure
    // allowExpiredAuth: false,
    // contentType: "application/json", // pass null to disable the default header
    // analytics: true,
  },
  async ({ req, res, redis, logger, startTime, origin, user, body }) => {
    // `user` is the authenticated user (never null when auth: "required"/"admin")
    // `body` is the parsed + validated payload (typed from bodySchema)
    logger.info("creating thing", { username: user!.username });

    // ...business logic against redis...

    logger.response(201, Date.now() - startTime);
    res.status(201).json({ success: true });
  }
);

Handler context

apiHandler passes { req, res, redis, logger, startTime, origin, user, body }:

• redis — client from createRedis() (Upstash REST or standard Redis backend).
• logger — request-scoped logger; request() is already called for you.
• user — null unless authenticated; guaranteed non-null for auth: "required"/"admin".
• body — null unless parseJsonBody/bodySchema; typed when bodySchema is set.

Auth

Auth is unified through _utils/request-auth.ts (resolveRequestAuth). Set auth on apiHandler:

• "none" — public.
• "optional" — anonymous allowed, but credentials are validated if present.
• "required" — needs both Authorization: Bearer <token> and X-Username: <username>. Partial creds → 400; bad pair → 401.
• "admin" — required auth AND username === "ryo", else 403.

For non-apiHandler routes (e.g. multipart uploads), call resolveRequestAuth() directly to keep behavior aligned.

Rate Limiting

Apply to public and expensive routes using _utils/_rate-limit.ts:

import * as RateLimit from "../_utils/_rate-limit.js";
import { getClientIp } from "../_utils/_rate-limit.js";

const ip = getClientIp(req);
const key = RateLimit.makeKey(["rl", "feature", "burst", "ip", ip]);
const result = await RateLimit.checkCounterLimit({ key, windowSeconds: 60, limit: 30 });

if (!result.allowed) {
  res.setHeader("Retry-After", String(result.resetSeconds));
  return res.status(429).json({
    error: "rate_limit_exceeded",
    limit: result.limit,
    retryAfter: result.resetSeconds,
  });
}

getClientIp respects TRUSTED_PROXY_COUNT when the API sits behind a reverse proxy. Prefer tiers from RATE_LIMIT_TIERS in _utils/constants.ts over magic numbers.

Response & Error Shape

• Success: explicit payloads ({ success: true }, { data: ... }).
• Client errors: 400/401/403/404/405/429 with JSON { error: "..." } (extra fields ok if additive).
• Server errors: 500 { error: "..." } — apiHandler provides this automatically for thrown errors.
• Streaming: use SSE helpers in _utils/_sse.ts; set stream headers and emit structured events (start, line, complete, error).

Shared Utilities (use before hand-rolling)

Always key Redis entries with REDIS_PREFIXES + shared TTL rather than hardcoding strings.

Manual Handlers (when apiHandler doesn't fit)

Some endpoints (e.g. multipart /api/audio-transcribe) keep explicit handlers. Mirror the shared behavior manually:

import { getEffectiveOrigin, isAllowedOrigin, setCorsHeaders } from "../_utils/_cors.js";
import { initLogger } from "../_utils/_logging.js";
import { resolveRequestAuth } from "../_utils/request-auth.js";

const origin = getEffectiveOrigin(req);
setCorsHeaders(res, origin, { methods: ["POST", "OPTIONS"] });
if (req.method === "OPTIONS") return res.status(204).end();
if (!isAllowedOrigin(origin)) return res.status(403).json({ error: "Unauthorized" });
// method checks → initLogger() + timing logs → resolveRequestAuth() for auth routes

Testing

API integration tests require the standalone server running:

# Terminal 1
bun run dev:api          # exports TRUSTED_PROXY_COUNT=1 for spoofed-IP rate-limit tests
# Terminal 2
bun run test:api         # or: bun test tests/integration/api/test-<feature>.test.ts

Use helpers from tests/helpers/test-utils.ts: fetchWithOrigin, fetchWithAuth, ensureUserAuth, makeRateLimitBypassHeaders (random IP to dodge rate limits). Place new API suites under tests/integration/api/ and append them to API_TEST_FILES in scripts/test-groups.ts, then run bun run test:registration. For pure schema/validation logic, a no-server unit test under tests/unit/ (see the write-tests skill) is often enough.

Best Practices

1. Prefer apiHandler; keep auth semantics via request-auth.
2. Validate ALL user input before use (Zod bodySchema is preferred).
3. Rate-limit public/expensive routes.
4. Keep response shapes stable, explicit, and backward-compatible.
5. Use SSRF-safe fetch for untrusted URLs.
6. Log request/response and key branch decisions.
7. Update docs/8.*.md whenever a request/response contract changes.