Api design expert

Skill shipshitdev/skills/skills/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.From its SKILL.md

Install

npx -y skills add shipshitdev/skills --skill api-design-expert

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.

SKILL.md

2.1 KB, as published. Nobody here has run it

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:

Check .agents/memory/ for API patterns and architecture notes
Review existing controllers and DTOs
Check for OpenAPI/Swagger setup
Review versioning strategy

Core Principles

RESTful Design

// 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

// Single resource
{ "data": {...}, "meta": {...} }

// List with pagination
{ "data": [...], "pagination": { "page", "limit", "total" } }

Error Format

{
  "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