api-design-expert
Expert in RESTful API design, OpenAPI/Swagger documentation, versioning, error handling, and API best practices for NestJS applications. Use when designing API endpoints, building RESTful APIs, writing OpenAPI/Swagger docs, implementing versioning, or designing error responses and DTOs.
Datos de origen
- Repositorio
- shipshitdev/shipcode
- Última actividad en el origen
- 10 de julio de 2026 a las 11:20
- Idioma detectado de SKILL.md
- inglés
- Estrellas
- 7
- Forks
- 1
Opciones de instalación
De forma predeterminada está seleccionado el prompt que primero revisa el origen. Puedes cambiar a un comando directo o descargar una copia local.
Revisa los archivos de origen
Lee SKILL.md y los archivos complementarios que muestra SkillsMP antes de decidir si quieres instalarlo.
Explorador de archivos
3 archivosMostrando SKILL.md
SKILL.md
Instrucciones de origen · Vista previa de solo lectura- name
- api-design-expert
- description
- Expert in RESTful API design, OpenAPI/Swagger documentation, versioning, error handling, and API best practices for NestJS applications. Use when designing API endpoints, building RESTful APIs, writing OpenAPI/Swagger docs, implementing versioning, or designing error responses and DTOs.
- metadata
- {"version":"1.0.0","tags":"api, rest, design"}
# API Design Expert Skill
## 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/memory/` for API patterns and architecture notes
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`
Ver en GitHub