home / skills / shipshitdev / library / api-design-expert
This skill guides RESTful API design and OpenAPI documentation for NestJS apps, improving versioning, error handling, and DTO validation.
npx playbooks add skill shipshitdev/library --skill api-design-expertReview the files below or copy the command above to add this skill to your agents.
---
name: api-design-expert
description: Expert in RESTful API design, OpenAPI/Swagger documentation, versioning, error handling, and API best practices for NestJS applications
---
# API Design Expert Skill
Expert in RESTful API design, OpenAPI/Swagger documentation, versioning strategies, error handling, and API best practices for NestJS applications.
## When to Use
- Designing new API endpoints
- Creating RESTful APIs
- Writing OpenAPI/Swagger documentation
- Implementing API versioning
- Designing error responses
- Creating DTOs and validation
- Implementing pagination, filtering, sorting
## Project Context Discovery
Before providing guidance:
1. Check `.agents/SYSTEM/ARCHITECTURE.md` for API patterns
2. Review existing controllers and DTOs
3. Check for OpenAPI/Swagger setup
4. Review versioning strategy
## Core Principles
### RESTful Design
```typescript
// Use nouns, plural, hierarchical
GET /api/users
GET /api/users/:id
POST /api/users
PUT /api/users/:id
DELETE /api/users/:id
GET /api/users/:id/posts
```
### HTTP Status Codes
- `200 OK` / `201 Created` / `204 No Content`
- `400 Bad Request` / `401 Unauthorized` / `403 Forbidden`
- `404 Not Found` / `409 Conflict` / `500 Internal Server Error`
### Response Format
```typescript
// Single resource
{ "data": {...}, "meta": {...} }
// List with pagination
{ "data": [...], "pagination": { "page", "limit", "total" } }
```
### Error Format
```typescript
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": [...],
"timestamp": "...",
"path": "/api/users"
}
}
```
## Best Practices
- Consistent naming conventions
- Validate all inputs with DTOs
- OpenAPI/Swagger documentation
- Authentication on all endpoints
- Pagination for lists
- Version APIs from the start
---
**For complete DTO examples, pagination/filtering/sorting patterns, versioning strategies, OpenAPI setup, CRUD controller patterns, nested resources, bulk operations, and anti-patterns, see:** `references/full-guide.md`
This skill is an API design expert focused on RESTful APIs, OpenAPI/Swagger documentation, versioning, error handling, and API best practices for NestJS applications. It provides concrete guidance for endpoint design, DTOs and validation, response shapes, and operational patterns like pagination and filtering. The aim is to produce consistent, maintainable APIs that integrate well with NestJS tooling and OpenAPI generation.
I inspect project controllers, DTOs, and existing OpenAPI setup to determine current patterns and gaps. I recommend concrete changes: route naming, status codes, response and error formats, DTO validation rules, and a versioning strategy. I also provide sample controller/DTO snippets, pagination/filtering patterns, and guidance for documenting endpoints in Swagger.
Which versioning approach should I pick?
Choose URI versioning for public APIs for clarity (e.g., /v1/...), or header versioning for internal APIs when you want cleaner paths; document any choice in OpenAPI and support redirected deprecation.
How should I format errors?
Return a structured error object with a code, human message, optional details array, timestamp, and request path so clients can programmatically react and surface helpful messages.