api-development
在Next.js App Router中开发和测试API路由。当用户请求创建、修改、测试或调试API端点、处理API响应、验证请求参数或使用/api目录时使用。
📖 中文导读:在Next.js App Router中开发和测试API路由。当用户请求创建、修改、测试或调试API端点、处理API响应、验证请求参数或使用/api目录时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: api-development description: "Develop and test API routes in the Next.js App Router. Use this when the user asks to create, modify, test, or debug API endpoints, handle API responses, validate request parameters, or work with the /api directory." allowed-tools: Read, Edit, Write, Grep, Glob, Bash
API Development Skill
This Skill helps develop, test, and debug API routes in the IsLeapYear Next.js application.
When to Use
- Creating new API endpoints
- Modifying existing API routes
- Testing API responses
- Debugging API errors
- Validating request parameters
- Working with API response helpers
Key Patterns
API Route Structure
All API routes follow Next.js 15 App Router patterns with async params:
export const GET = async (
request: NextRequest,
{ params }: { params: Promise<{ year: string }> }
) => {
const { year: yearParam } = await params;
const year = Number.parseInt(yearParam, 10);
if (Number.isNaN(year)) {
return errorResponse("Invalid year parameter");
}
return successResponse({ result: someData });
};
Response Helpers
Located in src/utils/response.ts:
successResponse<T>(data: T)- Returns 200 with standardized formaterrorResponse(message: string, status?: number)- Returns error response
Response format:
{
"status": 200,
"data": { ... },
"meta": { "timestamp": "2025-01-15T..." }
}
API Directory Structure
src/app/api/
├── check/ # Leap year check endpoints
│ ├── [year]/ # Single year: /api/check/2024
│ ├── batch/ # Batch checks
│ └── route.ts # Current year
├── calendar/ # Multi-calendar support
│ └── [type]/check/[year]/
└── stats/ # Statistics
├── range/
└── distribution/
Testing Commands
# Test current year endpoint
curl http://localhost:3000/api/check
# Test specific year
curl http://localhost:3000/api/check/2024
# Test batch endpoint
curl -X POST http://localhost:3000/api/check/batch \
-H "Content-Type: application/json" \
-d '{"years": [2024, 2025, 2026]}'
# Test calendar type
curl http://localhost:3000/api/calendar/gregorian/check/2024
Common Tasks
1. Creating a New Endpoint
- Determine the route path (e.g.,
/api/check/validate/[year]) - Create the directory structure
- Create
route.tswith GET/POST handlers - Use response helpers from
utils/response.ts - Validate all inputs
- Test with curl commands
2. Validating Parameters
Always validate:
- Year ranges (1582-9999 for Gregorian)
- Number parsing (use
Number.parseIntand checkNumber.isNaN) - Required fields for POST requests
- Calendar types (gregorian, julian, hebrew, chinese)
3. Error Handling
Return appropriate errors:
- 400 for invalid parameters
- 404 for not found
- 500 for server errors
Use errorResponse() helper for consistency.
Important Notes
- Always use
asyncfunctions for route handlers - Always
await paramsin dynamic routes (Next.js 15 requirement) - Use TypeScript for all routes
- Import response helpers:
import { successResponse, errorResponse } from "@/utils/response" - Test locally before deployment
- Follow the satirical tone for error messages when appropriate