Should I use nested routes?

Yes. Nested routes are supported; parent IDs are validated and mapped in middleware, and 404 is returned if the parent doesn't exist.

What about file upload endpoints?

For file uploads, add a multer middleware and accept multipart/form-data as part of the route.

How is authentication handled?

Auth middleware is applied at the route level; requests without a valid token return 401 when auth is required.

api-endpoint

Scanned

npx machina-cli add skill zakelfassi/skills-driven-development/api-endpoint --openclaw

Files (1)

SKILL.md

2.3 KB

API Endpoint Scaffold

Create a new REST API endpoint following project conventions.

Inputs

Entity name (singular, e.g., comment)
Fields (name:type pairs, e.g., body:string, author_id:number)
Auth required? (boolean, defaults to true)
Nested under? (optional parent entity, e.g., post)

Steps

Create the route file
```
src/routes/{entity}.routes.ts
```
- Define CRUD routes: GET /, GET /:id, POST /, PUT /:id, DELETE /:id
- If nested: GET /{parent}s/:parentId/{entity}s
Create the controller
```
src/controllers/{entity}.controller.ts
```
- One method per route
- All responses use { data, error, meta } shape
- Handle not-found with 404, validation with 422
Create the validation schema
```
src/validators/{entity}.validator.ts
```
- Use Zod schemas matching the field definitions
- Separate schemas for create vs. update (update = partial)
Create the test file
```
tests/api/{entity}.test.ts
```
- Test each CRUD operation
- Test validation (bad input returns 422)
- Test auth (if required: 401 without token)
- Use test factories for fixtures
Register the route
```
src/routes/index.ts
```
- Add import + app.use('/{entity}s', {entity}Routes)
- If auth required: add auth middleware

Conventions

Route paths are plural (/comments, not /comment)
File names are singular (comment.routes.ts)
All endpoints return { data, error, meta }
meta includes pagination for list endpoints
Auth middleware is applied at the route level, not controller level

Edge Cases

File upload endpoints: Add multer middleware, accept multipart/form-data
Nested routes: Parent ID is validated in middleware (404 if parent doesn't exist)
Soft delete: DELETE sets deleted_at timestamp, doesn't remove the row

Source

git clone https://github.com/zakelfassi/skills-driven-development/blob/main/examples/webapp-starter/skills/api-endpoint/SKILL.md

View on GitHub

Overview

This skill scaffolds a new REST API endpoint following project conventions. It creates the route, controller methods, validation schemas, and tests to ensure consistent data responses and error handling.

How This Skill Works

It generates a route file with full CRUD endpoints, a controller with one method per route returning { data, error, meta }, a Zod-based validator for create and update (update is partial), and a tests file that covers CRUD, validation, and auth. It also registers the route in src/routes/index.ts and enforces route-level auth when required.

When to Use It

You are creating a new API endpoint for a new resource (e.g., comment).
You need to add a backend route with standard CRUD operations.
You require validation and tests for every new endpoint.
You want to enforce project conventions (plural routes, single-file naming).
You are wiring up nested routes or edge cases like file uploads.

Quick Start

Step 1: Create route, controller, and validator files at src/routes/{entity}.routes.ts, src/controllers/{entity}.controller.ts, and src/validators/{entity}.validator.ts with CRUD definitions and Zod schemas.
Step 2: Write tests in tests/api/{entity}.test.ts to cover all CRUD operations, 422 validations, and 401 auth when required.
Step 3: Register the route in src/routes/index.ts (app.use('/{entity}s', {entity}Routes)) and run the test suite.

Best Practices

Name files and routes using the project conventions (singular file names, plural routes).
Return responses in the { data, error, meta } shape for all endpoints.
Use separate Zod schemas for create vs update (update should be partial).
Test all CRUD operations plus validation and auth when required.
Apply auth middleware at the route level, not inside controllers.

Example Use Cases

Create a new GET/POST/PUT/DELETE endpoint for 'comment' with fields body:string, author_id:number.
Nest a comments endpoint under posts: GET /posts/:postId/comments and related routes.
Implement a soft delete: DELETE sets deleted_at without removing the row.
Add file upload support by integrating multer for multipart/form-data.
Add tests covering 401 auth failures when tokens are missing for protected routes.

Frequently Asked Questions

Add this skill to your agents