home / skills / hoangnguyen0403 / agent-skills-standard / api-standards

api-standards skill

safe

This skill enforces standardized NestJS API responses, pagination, and error handling to improve consistency and developer experience.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill api-standards

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.3 KB

---
name: NestJS API Standards
description: Response wrapping, pagination, and error standardization.
metadata:
  labels: [nestjs, api, pagination, response]
  triggers:
    files: ['**/*.controller.ts', '**/*.dto.ts']
    keywords: [ApiResponse, Pagination, TransformInterceptor]
---

# NestJS API Standards & Common Patterns

## **Priority: P1 (OPERATIONAL)**

Standardized API response patterns and common NestJS conventions.

## Generic Response Wrapper

- **Concept**: Standardize all successful API responses.
- **Implementation**: Use `TransformInterceptor` to wrap data in `{ statusCode, data, meta }`.

## Pagination Standards (Pro)

- **DTOs**: Use strict `PageOptionsDto` (page/take/order) and `PageDto<T>` (data/meta).
- **Swagger Logic**: Generics require `ApiExtraModels` and schema path resolution.
- **Reference**: See [Pagination Wrapper Implementation](references/pagination-wrapper.md) for the complete `ApiPaginatedResponse` decorator code.

## Custom Error Response

- **Standard Error Object**:

  ```typescript
  export class ApiErrorResponse {
    @ApiProperty()
    statusCode: number;

    @ApiProperty()
    message: string;

    @ApiProperty()
    error: string;

    @ApiProperty()
    timestamp: string;

    @ApiProperty()
    path: string;
  }
  ```

- **Docs**: Apply `@ApiBadRequestResponse({ type: ApiErrorResponse })` globally or per controller.

Overview

This skill captures NestJS API standards for consistent response wrapping, pagination, and error formatting. It codifies interceptors, DTO patterns, and Swagger integrations so APIs are predictable for clients and easier to document. The focus is practical: simple response envelopes, typed pagination DTOs, and a standard error contract.

How this skill works

The skill recommends using a TransformInterceptor to wrap all successful responses into a uniform envelope with fields like statusCode, data, and meta. For list endpoints it defines PageOptionsDto and a generic PageDto<T> to carry data and pagination metadata. For error handling it prescribes a shared ApiErrorResponse class and documenting bad responses with @ApiBadRequestResponse or global exception filters to ensure consistent error payloads.

When to use it

Building REST APIs with NestJS that must return consistent response shapes
When you need standardized pagination and typed metadata for list endpoints
On teams that require uniform error payloads for client integration and monitoring
When auto-generating Swagger docs that must represent generic paginated responses
When designing public APIs where predictable envelopes simplify client parsing

Best practices

Use a global TransformInterceptor to apply the response wrapper for all controllers
Define strict DTOs for pagination: PageOptionsDto (page, take, order) and PageDto<T>
Register generic models in Swagger with ApiExtraModels and resolved schema paths
Use a single ApiErrorResponse class and apply it via @ApiBadRequestResponse or global filters
Keep envelope minimal: statusCode, data, and meta for success; statusCode, message, error, timestamp, path for errors

Example use cases

Standardizing responses across multiple microservices so clients consume a single envelope format
Implementing paginated product listing endpoints with PageOptionsDto and PageDto<ProductDto>
Documenting paginated endpoints in Swagger using ApiPaginatedResponse decorator and ApiExtraModels
Providing consistent error responses from validation and runtime exceptions for improved client UX
Enforcing API contracts in a backend-for-frontend where clients rely on meta.pagination fields

FAQ

How do I include generics in Swagger for paginated responses?

Register generic models with ApiExtraModels and use decorators that resolve schema paths to expose PageDto<T> correctly in Swagger.

Should I wrap error responses with the same envelope as success responses?

No. Use a dedicated ApiErrorResponse structure for errors to convey statusCode, message, error, timestamp, and path clearly.