API Design Agent Skill
REST conventions, Zod validation, and consistent error formats.
The Skill
Full content, every format. Copy it, download it, or install with one command.
---
description: REST conventions, Zod validation, and consistent error formats.
homepage: https://yepapi.com/skills/api-design
metadata:
tags: [api, rest, validation, zod]
---
# API Design
## Rules
- RESTful naming: plural nouns, no verbs — `/users`, `/orders`, not `/getUsers`
- HTTP methods: GET (read), POST (create), PATCH (update), DELETE (remove)
- Input validation with Zod: parse request body before processing
- Consistent error format: `{ error: { code: string, message: string } }`
- Pagination: `?limit=20&offset=0` or cursor-based for large datasets
- Status codes: 200 (ok), 201 (created), 400 (bad request), 401 (unauthorized), 404 (not found), 500 (server error)
- Rate limiting: per-key or per-IP, return `429` with `Retry-After` header
- API versioning via URL prefix: `/v1/resource`
## Avoid
- Verbs in URLs: `/getUser/123` — use `GET /users/123`
- Inconsistent error shapes across endpoints
- Returning 200 for errors with `{ success: false }` — use proper HTTP status codes
- Missing input validation — never trust client inputInstall
Why Use the API Design Skill?
Without this skill, your AI guesses at api design patterns. It might hallucinate deprecated APIs, use outdated conventions, or miss best practices entirely. With it, your AI follows a proven ruleset — every suggestion aligns with current standards.
Drop this skill into your project and your AI instantly knows the rules. Better code suggestions, fewer errors, faster shipping.
Try These Prompts
These prompts work better with the API Design skill installed. Your AI knows the context and writes code that fits.
"Design a REST API with proper resource naming, Zod validation, and consistent error responses"
"Create a versioned API with pagination, filtering, and rate limiting middleware"
"Build a type-safe API layer with request/response schemas and OpenAPI documentation"
Works Great With
API Design skill — FAQ
It enforces REST conventions, Zod validation schemas, and consistent error response formats. Your AI designs APIs with proper resource naming, status codes, and type-safe validation.
Run `npx skills add YepAPI/skills --skill api-design` in your project root. This copies the skill file into your repo where your AI coding tool can read it automatically.
The skill focuses on REST conventions with Zod validation. REST is simpler to cache, debug, and document. If your data has many nested relationships, consider GraphQL, but REST covers most use cases well.