Api Design Expert

What it does

This skill provides expert guidance on designing RESTful APIs, particularly within NestJS applications. It assists with creating API endpoints, generating OpenAPI/Swagger documentation, implementing versioning strategies, and ensuring proper error handling. The skill emphasizes adherence to best practices for backend service development and API workflows, including DTO creation and validation.

When to use it

• Designing new API endpoints for a NestJS application.
• Creating RESTful APIs from scratch or refactoring existing ones.
• Generating OpenAPI/Swagger documentation for your API.
• Implementing versioning strategies to manage API evolution.
• Defining and designing effective error responses.

Key capabilities

• RESTful API design principles (using nouns, pluralization, hierarchical structures).
• OpenAPI/Swagger documentation generation.
• API versioning strategy implementation.
• Error response design with standardized formats including code, message, details, timestamp, and path.
• DTO creation and input validation.
• Implementation of pagination, filtering, and sorting for lists.
• Guidance on HTTP status codes (200, 201, 204, 400, 401, 403, 404, 409, 500).

Example prompts

• "I need to design a new API endpoint for retrieving user posts. What should the URL structure be?"
• "Can you help me create an OpenAPI/Swagger definition for my /users endpoint?"
• "What's the best way to implement versioning for this API?"

Tips & gotchas

• Before seeking guidance, review your project’s ARCHITECTURE.md file (located in .agents/SYSTEM/) for established API patterns.
• The skill is specifically tailored for NestJS applications; results may vary with other frameworks.
• For more comprehensive examples and detailed guides on topics like pagination, filtering, sorting, OpenAPI setup, and anti-patterns, consult the references/full-guide.md file.