api-endpoint-generator — Claude Code skill: API, install
api-endpoint-generator builds CRUD REST APIs with request checks, TypeScript types, shared response shapes, error handling, and docs. Use it for backend routes and API work.
MIT 294 installs ★ 64 updated 2026-01-12
npx skills add patricio0312rev/skills --skill api-endpoint-generator -a claude-codeWhat api-endpoint-generator does
This skill turns a resource definition into a CRUD API plan and implementation: POST, GET, PUT or PATCH, and DELETE routes, request checks for bodies and query parameters, typed responses, and consistent errors. Its examples use Zod or Joi for schemas, TypeScript interfaces for the API contract, OpenAPI or Swagger documentation, plus request and response samples.
The shown layout targets Express with TypeScript. It separates types, schemas, routes, controllers, and validation middleware; the controller calls a service and returns an ApiResponse, including a missing-resource error. The example is tied to Express and TypeScript, so another stack needs a different file structure.
What it helps with
- generate CRUD routes for a resource
- validate request bodies and query parameters
- define typed TypeScript API responses
- standardize API error payloads
- write OpenAPI or Swagger documentation
Example prompts for the agent
- Generate a CRUD REST API for a
Userresource with Express and TypeScript, usingtypes/user.types.ts,schemas/user.schema.ts, androutes/users.routes.ts. - Add Zod validation, typed responses, one error shape, and POST, GET, PATCH, and DELETE handlers for these routes.
- Create OpenAPI documentation with request and response samples for the generated API.
How to install api-endpoint-generator
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill api-endpoint-generator -a claude-code2Manually: put the files in place
~/.claude/skills/api-contract-normalizer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/api-contract-normalizer/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill api-endpoint-generator -a codex2Manually: put the files in place
.agents/skills/api-contract-normalizer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill api-endpoint-generator -a cursor2Manually: put the files in place
.cursor/skills/api-contract-normalizer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install patricio0312rev/skills backend/api-contract-normalizer/SKILL.md2Manually: put the files in place
.github/skills/api-contract-normalizer/SKILL.md1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill api-endpoint-generator -a gemini-cli2Platform CLI
gemini skills install https://github.com/patricio0312rev/skills --path backend/api-contract-normalizerManually: put the files in place
.devin/skills/api-contract-normalizer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill api-endpoint-generator -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about api-endpoint-generator
How do I install api-endpoint-generator in Claude Code?
Run npx skills add patricio0312rev/skills --skill api-contract-normalizer -a claude-code, then open ~/.claude/skills/api-contract-normalizer/SKILL.md.
What does api-endpoint-generator do?
It generates CRUD REST API routes with Zod or Joi validation, TypeScript response types, shared response formats, error handling, and OpenAPI or Swagger documentation.
Which stack does the api-endpoint-generator example use?
The example is built around Express and TypeScript. Zod is used for validation, while Joi is also listed as an option.
Source text
SKILL.md · MIT
---
name: api-endpoint-generator
description: Generates CRUD REST API endpoints with request validation, TypeScript types, consistent response formats, error handling, and documentation. Includes route handlers, validation schemas (Zod/Joi), typed responses, and usage examples. Use when building "REST API", "CRUD endpoints", "API routes", or "backend endpoints".
---
# API Endpoint Generator
Generate production-ready CRUD API endpoints with validation and type safety.
## Core Workflow
1. **Define resource**: Entity name and schema
2. **Generate routes**: POST, GET, PUT/PATCH, DELETE endpoints
3. **Add validation**: Request body/query validation with Zod/Joi
4. **Type responses**: TypeScript interfaces for all responses
5. **Error handling**: Consistent error responses
6. **Documentation**: OpenAPI/Swagger specs
7. **Examples**: Request/response samples
## Express + TypeScript Pattern
```typescript
// types/user.types.ts
export interface User {
id: string;
email: string;
name: string;
role: "user" | "admin";
createdAt: Date;
updatedAt: Date;
}
export interface CreateUserDto {
email: string;
name: string;
password: string;
}
export interface UpdateUserDto {
name?: string;
email?: string;
}
export interface ApiResponse<T> {
success: boolean;
data?: T;
error?: ApiError;
meta?: PaginationMeta;
}
export interface ApiError {
code: string;
message: string;
details?: Record<string, string[]>;
}
```
## Validation Schemas (Zod)
```typescript
// schemas/user.schema.ts
import { z } from "zod";
export const createUserSchema = z.object({
email: z.string().email("Invalid email address"),
name: z.string().min(2, "Name must be at least 2 characters"),
password: z
.string()
.min(8, "Password must be at least 8 characters")
.regex(/[A-Z]/, "Password must contain uppercase letter")
.regex(/[0-9]/, "Password must contain number"),
});
export const updateUserSchema = z
.object({
name: z.string().min(2).optional(),
email: z.string().email().optional(),
})
.refine((data) => Object.keys(data).length > 0, {
message: "At least one field must be provided",
});
export const getUsersQuerySchema = z.object({
page: z.coerce.number().int().positive().default(1),
limit: z.coerce.number().int().min(1).max(100).default(10),
sortBy: z.enum(["name", "email", "createdAt"]).optional(),
sortOrder: z.enum(["asc", "desc"]).default("desc"),
search: z.string().optional(),
});
export type CreateUserDto = z.infer<typeof createUserSchema>;
export type UpdateUserDto = z.infer<typeof updateUserSchema>;
export type GetUsersQuery = z.infer<typeof getUsersQuerySchema>;
```
## CRUD Route Handlers
```typescript
// routes/users.routes.ts
import { Router } from "express";
import { UserController } from "../controllers/user.controller";
import { validateRequest } from "../middleware/validate";
import { authenticate } from "../middleware/auth";
import {
createUserSchema,
updateUserSchema,
getUsersQuerySchema,
} from "../schemas/user.schema";
const router = Router();
const controller = new UserController();
// Create
router.post(
"/",
authenticate,
validateRequest({ body: createUserSchema }),
controller.create
);
// Read (list)
router.get(
"/",
authenticate,
validateRequest({ query: getUsersQuerySchema }),
controller.list
);
// Read (single)
router.get("/:id", authenticate, controller.getById);
// Update
router.patch(
"/:id",
authenticate,
validateRequest({ body: updateUserSchema }),
controller.update
);
// Delete
router.delete("/:id", authenticate, controller.delete);
export default router;
```
## Controller Implementation
```typescript
// controllers/user.controller.ts
import { Request, Response, NextFunction } from "express";
import { UserService } from "../services/user.service";
import {
CreateUserDto,
UpdateUserDto,
GetUsersQuery,
} from "../types/user.types";
import { ApiResponse } from "../types/api.types";
export class UserController {
private service = new UserService();
create = async (
req: Request<{}, {}, CreateUserDto>,
res: Response<ApiResponse<User>>,
next: NextFunction
) => {
try {
const user = await this.service.create(req.body);
res.status(201).json({
success: true,
data: user,
});
} catch (error) {
next(error);
}
};
list = async (
req: Request<{}, {}, {}, GetUsersQuery>,
res: Response<ApiResponse<User[]>>,
next: NextFunction
) => {
try {
const { page, limit, sortBy, sortOrder, search } = req.query;
const result = await this.service.findAll({
page,
limit,
sortBy,
sortOrder,
search,
});
res.json({
success: true,
data: result.users,
meta: {
page: result.page,
limit: result.limit,
total: result.total,
totalPages: result.totalPages,
},
});
} catch (error) {
next(error);
}
};
getById = async (
req: Request<{ id: string }>,
res: Response<ApiResponse<User>>,
next: NextFunction
) => {
try {
const user = await this.service.findById(req.params.id);
if (!user) {
return res.status(404).json({
success: false,
error: {
code: "USER_NOT_FOUND",
message: "User not found",
},
});
}
res.json({
success: true,
data: user,
});
} catch (error) {
next(error);
}
};
update = async (
req: Request<{ id: string }, {}, UpdateUserDto>,
res: Response<ApiResponse<User>>,
next: NextFunction
) => {
try {
const user = await this.service.update(req.params.id, req.body);
if (!user) {
return res.status(404).json({
success: false,
error: {
code: "USER_NOT_FOUND",
message: "User not found",
},
});
}
res.json({
success: true,
data: user,
});
} catch (error) {
next(error);
}
};
delete = async (
req: Request<{ id: string }>,
res: Response<ApiResponse<void>>,
next: NextFunction
) => {
try {
const deleted = await this.service.delete(req.params.id);
if (!deleted) {
return res.status(404).json({
success: false,
error: {
code: "USER_NOT_FOUND",
message: "User not found",
},
});
}
res.status(204).send();
} catch (error) {
next(error);
}
};
}
```
## Validation Middleware
```typescript
// middleware/validate.ts
import { Request, Response, NextFunction } from "express";
import { ZodSchema } from "zod";
interface ValidationSchemas {
body?: ZodSchema;
query?: ZodSchema;
params?: ZodSchema;
}
export const validateRequest = (schemas: ValidationSchemas) => {
return (req: Request, res: Response, next: NextFunction) => {
try {
if (schemas.body) {
req.body = schemas.body.parse(req.body);
}
if (schemas.query) {
req.query = schemas.query.parse(req.query);
}
if (schemas.params) {
req.params = schemas.params.parse(req.params);
}
next();
} catch (error) {
if (error instanceof z.ZodError) {
return res.status(400).json({
success: false,
error: {
code: "VALIDATION_ERROR",
message: "Invalid request data",
details: error.flatten().fieldErrors,
},
});
}
next(error);
}
};
};
```
## NestJS Pattern
```typescript
// users/users.controller.ts
import {
Controller,
Get,
Post,
Put,
Delete,
Body,
Param,
Query,
} from "@nestjs/common";
import { ApiTags, ApiOperation, ApiResponse } from "@nestjs/swagger";
import { UsersService } from "./users.service";
import { CreateUserDto, UpdateUserDto, GetUsersQueryDto } from "./dto";
@ApiTags("users")
@Controller("users")
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Post()
@ApiOperation({ summary: "Create user" })
@ApiResponse({ status: 201, description: "User created" })
@ApiResponse({ status: 400, description: "Validation error" })
async create(@Body() dto: CreateUserDto) {
return this.usersService.create(dto);
}
@Get()
@ApiOperation({ summary: "List users" })
async findAll(@Query() query: GetUsersQueryDto) {
return this.usersService.findAll(query);
}
@Get(":id")
@ApiOperation({ summary: "Get user by ID" })
async findOne(@Param("id") id: string) {
return this.usersService.findOne(id);
}
@Put(":id")
@ApiOperation({ summary: "Update user" })
async update(@Param("id") id: string, @Body() dto: UpdateUserDto) {
return this.usersService.update(id, dto);
}
@Delete(":id")
@ApiOperation({ summary: "Delete user" })
async remove(@Param("id") id: string) {
return this.usersService.remove(id);
}
}
```
## FastAPI Pattern (Python)
```python
# routers/users.py
from fastapi import APIRouter, Depends, HTTPException, Query
from typing import List, Optional
from pydantic import BaseModel, EmailStr, Field
router = APIRouter(prefix="/users", tags=["users"])
class CreateUserDto(BaseModel):
email: EmailStr
name: str = Field(..., min_length=2)
password: str = Field(..., min_length=8)
class UserResponse(BaseModel):
id: str
email: str
name: str
role: str
created_at: datetime
class PaginatedResponse(BaseModel):
data: List[UserResponse]
total: int
page: int
limit: int
@router.post("/", status_code=201, response_model=UserResponse)
async def create_user(dto: CreateUserDto, service: UserService = Depends()):
return await service.create(dto)
@router.get("/", response_model=PaginatedResponse)
async def list_users(
page: int = Query(1, ge=1),
limit: int = Query(10, ge=1, le=100),
search: Optional[str] = None,
service: UserService = Depends()
):
return await service.find_all(page, limit, search)
```
## Response Format Standards
```typescript
// Success Response
{
"success": true,
"data": { ... },
"meta": {
"page": 1,
"limit": 10,
"total": 50,
"totalPages": 5
}
}
// Error Response
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": {
"email": ["Invalid email address"],
"password": ["Password must contain uppercase letter"]
}
}
}
```
## Status Codes
- 200: Success (GET, PUT)
- 201: Created (POST)
- 204: No Content (DELETE)
- 400: Validation Error
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 409: Conflict
- 500: Server Error
## Best Practices
1. **Type everything**: Request, response, DTOs, errors
2. **Validate early**: Before hitting service layer
3. **Consistent responses**: Same structure everywhere
4. **HTTP semantics**: Use correct status codes
5. **Error details**: Include validation errors
6. **Pagination**: Always paginate lists
7. **Filtering/sorting**: Support common queries
8. **Documentation**: OpenAPI/Swagger specs
## Output Checklist
- [ ] Route definitions with HTTP methods
- [ ] Request validation schemas
- [ ] TypeScript types for all DTOs
- [ ] Controller handlers with error handling
- [ ] Consistent response format
- [ ] Pagination for list endpoints
- [ ] HTTP status codes correctly used
- [ ] Error response format
- [ ] OpenAPI/Swagger documentation
- [ ] Usage examples with curl/requests
© patricio0312rev · MIT · patricio0312rev/skills