API Standards Validator

Validate REST API design standards compliance including versioning, naming conventions, HTTP methods, status codes, pagination, and Swagger documentation.

What This Skill Does

Performs comprehensive API standards validation:

• Versioning: Checks /v1/ prefix on all routes
• Resource Naming: Validates plural nouns, lowercase-with-hyphens
• HTTP Methods: Validates proper method usage and status codes
• Pagination: Ensures list endpoints support pagination
• Swagger Docs: Verifies complete OpenAPI documentation
• Error Mapping: Checks proper status code usage

When to Use This Skill

Use when you need to:

• Validate API endpoints before deployment
• Check new endpoints for standards compliance
• Review API design during code review
• Ensure Swagger documentation completeness

Examples:

• "Validate the User API endpoints"
• "Check if Product API follows design standards"
• "Review Order API for compliance"

API Design Standards

Versioning Rules

All controllers MUST be prefixed with /v1/:

// ✅ CORRECT
@JsonController('/v1/users')
export class UserController {}

@JsonController('/v1/sms-messages')
export class SmsMessageController {}

// ❌ WRONG
@JsonController('/users')  // Missing version
@JsonController('/api/users')  // Wrong format

Resource Naming Rules

Must be:

• Plural nouns: /v1/users not /v1/user
• Lowercase with hyphens: /v1/sms-messages
• No verbs: /v1/users not /v1/getUsers

// ✅ CORRECT
'/v1/users'
'/v1/products'
'/v1/sms-messages'
'/v1/order-items'

// ❌ WRONG
'/v1/user'          // Singular
'/v1/getUsers'      // Verb
'/v1/Users'         // Wrong casing
'/v1/sms_messages'  // Underscores

HTTP Methods and Status Codes

Expected patterns:

• POST (Create) → 201 Created
• GET (Read) → 200 OK
• PATCH (Partial Update) → 200 OK
• PUT (Full Update) → 200 OK
• DELETE → 204 No Content

Error status codes:

• 400 Bad Request → Validation errors
• 401 Unauthorized → Authentication required
• 403 Forbidden → Permission denied
• 404 Not Found → Resource not found
• 409 Conflict → Duplicate resource
• 422 Unprocessable Entity → Business rule violation
• 500 Internal Server Error → Unexpected errors

Pagination Requirements

List endpoints MUST support pagination with DTOs:

// ✅ CORRECT
export class QueryEntityDto {
  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  @Min(1)
  limit?: number = 20;

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  @Min(0)
  offset?: number = 0;
  sortBy: z.enum(['createdAt', 'name']).optional(),
  order: z.enum(['asc', 'desc']).default('desc'),
});

// Response format
{
  items: Entity[],
  total: number,
  limit: number,
  offset: number
}

Swagger Documentation Requirements

All endpoints MUST have:

.post('/', controller.create.bind(controller), {
  body: CreateSchema,
  detail: {
    summary: 'Create entity',          // Required
    description: 'Detailed description', // Recommended
    tags: ['Entities'],                // Required
    responses: {                        // Required
      201: { description: 'Created' },
      400: { description: 'Invalid input' },
      409: { description: 'Duplicate' },
    },
  },
})

Validation Checks

Versioning Validation

Checks:

• All route prefixes include /v1/
• No routes without versioning
• Consistent version across all endpoints

Reports:

CRITICAL: Missing API version
File: src/contexts/user/presentation/user.routes.ts:5
Issue: Route prefix '/users' lacks /v1/
Fix: Change to '/v1/users'

Resource Naming Validation

Checks:

• Resources are plural nouns
• Lowercase with hyphens (not underscores or camelCase)
• No verbs in resource names
• Proper REST conventions

Reports:

CRITICAL: Singular resource name
File: src/contexts/user/presentation/user.routes.ts:5
Issue: Resource '/v1/user' is singular
Fix: Change to '/v1/users'

CRITICAL: Verb in resource name
File: src/contexts/user/presentation/user.routes.ts:10
Issue: Resource '/v1/getUsers' contains verb
Fix: Use '/v1/users' with GET method

HTTP Method Validation

Checks:

• GET for reads (200 OK)
• POST for creates (201 Created)
• PATCH/PUT for updates (200 OK)
• DELETE for deletions (204 No Content)
• Swagger responses match expected codes

Reports:

CRITICAL: Wrong status code for POST
File: src/contexts/user/presentation/user.routes.ts:15
Issue: POST endpoint documents 200, should be 201
Fix: Change response code to 201 in Swagger detail

Error Mapping Validation

Checks:

• Controllers map domain errors to HTTP exceptions
• Correct status codes used:
  • EntityNotFoundError → 404
  • DuplicateError → 409
  • ValidationError → 400
  • UnauthorizedError → 401
  • ForbiddenError → 403
  • BusinessRuleViolation → 422

Reports:

WARNING: Missing error mapping
File: src/contexts/user/presentation/user.controller.ts:20
Issue: EntityNotFoundError not mapped to HttpException
Fix: Add error mapping:
  if (error instanceof EntityNotFoundError) {
    throw new HttpException(404, error.message, error.code);
  }

Pagination Validation

Checks:

• List endpoints have limit parameter
• List endpoints have offset parameter
• Defaults defined for pagination
• Response includes total count

Reports:

CRITICAL: Missing pagination
File: src/contexts/user/presentation/schemas/query-user.schema.ts
Issue: Query schema lacks limit and offset
Fix: Add pagination fields:
  limit: z.coerce.number().min(1).max(100).default(10),
  offset: z.coerce.number().min(0).default(0),

Swagger Documentation Validation

Checks:

• All endpoints have detail object
• summary field present
• tags array present
• responses object with status codes
• Response descriptions provided

Reports:

WARNING: Incomplete Swagger documentation
File: src/contexts/user/presentation/user.routes.ts:15
Issue: POST endpoint missing 'responses' in detail
Fix: Add responses object:
  responses: {
    201: { description: 'User created' },
    400: { description: 'Invalid input' },
    409: { description: 'Email exists' },
  }

Controller Binding Validation

Checks:

• Controller methods use .bind(controller)
• Controller resolved from DI container

Reports:

CRITICAL: Controller method not bound
File: src/contexts/user/presentation/user.routes.ts:12
Issue: .post('/', controller.create) missing .bind()
Fix: Add .bind(controller): .post('/', controller.create.bind(controller))

Common Violations

Missing Versioning

// ❌ WRONG
new Elysia({ prefix: '/users' })

// ✅ CORRECT
new Elysia({ prefix: '/v1/users' })

Wrong Resource Naming

// ❌ WRONG - Singular
new Elysia({ prefix: '/v1/user' })

// ❌ WRONG - Verb
.get('/getUser', ...)

// ✅ CORRECT
new Elysia({ prefix: '/v1/users' })
.get('/:id', ...)

Wrong Status Code

// ❌ WRONG
.post('/', ..., {
  detail: {
    responses: {
      200: {} // Should be 201 for POST
    }
  }
})

// ✅ CORRECT
.post('/', ..., {
  detail: {
    responses: {
      201: { description: 'Created' }
    }
  }
})

Missing Pagination

// ❌ WRONG
export const QuerySchema = z.object({
  search: z.string().optional(),
});

// ✅ CORRECT
export const QuerySchema = z.object({
  limit: z.coerce.number().min(1).max(100).default(10),
  offset: z.coerce.number().min(0).default(0),
  search: z.string().optional(),
});

Incomplete Swagger

// ❌ WRONG
.post('/', controller.create.bind(controller), {
  body: CreateSchema,
})

// ✅ CORRECT
.post('/', controller.create.bind(controller), {
  body: CreateSchema,
  detail: {
    summary: 'Create user',
    tags: ['Users'],
    responses: {
      201: { description: 'User created' },
      400: { description: 'Invalid input' },
    },
  },
})

Report Format

1. Summary: Endpoints validated
2. Endpoint Inventory: List all found endpoints
3. Critical Issues: Must fix immediately
4. Warnings: Should fix before deployment
5. Suggestions: Nice-to-have improvements
6. Compliance Score: Percentage of standards met

Integration

The validator is read-only - it never modifies code. After review:

1. Fix critical issues (versioning, naming)
2. Address warnings (Swagger docs, pagination)
3. Consider suggestions (additional docs)
4. Re-run validator to verify compliance

Related Skills

• ddd-validator: Validate DDD architecture
• ddd-api-generator: Generate compliant APIs
• di-helper: Check DI setup