skills.rest
ryokun6
ryokun6COMMUNITY
Explore all skills by this author →
Website𝕏@ryolu_GitHub

write-api-route

Creates ryOS backend API routes using the apiHandler wrapper with auth, rate limiting, and Redis conventions.

1.2k|181|Updated Jan 28, 2025
Search Tags:#api#zod#Redis#Bun#Backend#Authentication#Rate limiting
One-click install
npx skills add https://github.com/ryokun6/ryos --skill write-api-route
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-api-route
Source: https://github.com/ryokun6/ryos/tree/main/.cursor/skills/write-api-route
Command: npx skills add https://github.com/ryokun6/ryos --skill write-api-route

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires zod.

What problem does it solve?

Adding a new backend endpoint in ryOS requires following many project-specific conventions—CORS handling, origin allowlisting, auth resolution, Zod validation, Redis key prefixes, rate limiting, and structured logging. This Skill encodes those conventions so new API routes under api/ are consistent and correct on the first pass.

Core Features & Use Cases

  • Standardized Route Scaffolding: Guides creation of collection routes (api/<feature>/index.ts) and item routes ([id].ts) wrapped in the shared apiHandler with typed Zod bodySchema validation.
  • Auth & Rate Limiting: Applies the unified request-auth modes (none, optional, required, admin) and counter-based rate limits via _utils/_rate-limit.ts with proxy-aware client IP detection.
  • Testing & Docs Workflow: Directs integration tests under tests/integration/api/ against the standalone Bun server and keeps docs/8.*.md contracts in sync.
  • Use Case: You need a new authenticated POST endpoint that stores data in Redis. The Skill walks you through wrapping the handler in apiHandler, validating input with Zod, rate-limiting by IP, and writing the matching integration test.

Quick Start

Ask the assistant to create a new authenticated POST API route under api/ for your feature using the apiHandler pattern with Zod validation and rate limiting.

Frequently Asked Questions about write-api-route

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new API route in ryOS?▼

Create a file under api/<feature>/index.ts for collections or [id].ts for item routes, then export a handler wrapped in apiHandler with methods, auth mode, and an optional Zod bodySchema. Import shared modules with the .js extension for Node-style ESM resolution.

How does authentication work for ryOS API endpoints?▼

Set the auth option on apiHandler to none, optional, required, or admin. Required auth needs both an Authorization Bearer token and an X-Username header, while admin additionally requires the username to be ryo. Non-apiHandler routes call resolveRequestAuth directly.

How do I rate limit a public API endpoint in ryOS?▼

Use checkCounterLimit from _utils/_rate-limit.ts with a key built from makeKey and the client IP from getClientIp. On rejection, return 429 with a Retry-After header, and prefer tiers from RATE_LIMIT_TIERS in _utils/constants.ts over hardcoded numbers.

When should I use a manual handler instead of apiHandler?▼

Use a manual handler for endpoints apiHandler does not fit, such as multipart uploads like audio transcription. You must then replicate CORS headers, origin checks, method validation, logging, and auth resolution yourself using the shared _utils modules.

How do I test ryOS API routes?▼

Run the standalone server with bun run dev:api in one terminal and bun run test:api in another. Place suites under tests/integration/api/, register them in scripts/test-groups.ts, and use helpers like fetchWithAuth and makeRateLimitBypassHeaders from tests/helpers/test-utils.ts.

Related Skills

Explore More Software Engineering Skills→
g-zenrg-zenr

design-api

Define API contracts with endpoints, Pydantic models, and auth considerations.

Community
Intermediate
DexploarerDexploarer
7

deployment-helper

Deploy ElizaOS agents to production with Docker, monitoring, and scaling.

Community
Advanced
lgzarturolgzarturo

cc-test-plan

Generate a Markdown test plan covering unit, integration, contract, edge cases, and regression.

Community
Intermediate
DanielPodolskyDanielPodolsky
274

backend-fundamentals

Evaluate API route handlers and backend architecture for RESTful design.

Community
Intermediate