api-conventions_skill

Overview

This skill codifies MX Space API design conventions for writing controllers, endpoints, and HTTP handlers in NestJS/TypeScript. It provides clear, opinionated patterns for routing, authentication, response shape, pagination, validation, error handling, idempotency, and caching. Apply it to keep APIs consistent, predictable, and production-ready.

How this skill works

The skill enforces decorator-based patterns: use @ApiController for routing with automatic versioned prefixes, @Auth and @IsAuthenticated for auth semantics, and Response/JSON interceptors to normalize output and snake_case fields. It standardizes pagination via an explicit Paginator decorator and requires specific return types for automatic pagination formatting. Error handling uses BusinessException and HTTP exceptions to map domain and transport errors cleanly.

When to use it

• When creating or refactoring NestJS controllers for MX Space services
• When you need consistent response shapes and snake_case JSON across APIs
• When implementing auth-sensitive endpoints with optional or required user context
• When adding paginated list endpoints that must return mongoose.PaginateResult
• When protecting create operations with idempotency or adding HTTP caching

Best practices

• Always use @ApiController instead of @Controller so environment prefixes are applied
• Mark protected endpoints with @Auth() and accept @CurrentUser() where user context is needed
• Return mongoose.PaginateResult for endpoints using @HTTPDecorators.Paginator to ensure correct pagination format
• Throw BusinessException for domain errors and standard Nest HTTP exceptions for transport-level errors
• Apply @HTTPDecorators.Idempotence() on create endpoints and use custom keys for non-standard deduplication
• Use @HttpCache or @HttpCache.disable explicitly to control caching behavior per endpoint

Example use cases

• Implementing a posts controller: @ApiController('posts'), create() guarded by @Auth(), list() using @HTTPDecorators.Paginator
• Building public read endpoints that optionally detect current user via @IsAuthenticated() to tailor response
• Creating transactional create endpoints with @HTTPDecorators.Idempotence({ key: 'create-post' }) to avoid duplicates
• Returning 204 for endpoints that yield undefined and 201 for successful resource creation
• Disabling cache on frequently changing list endpoints with @HttpCache.disable