Api design

Skill Roambee/claude-code-standards/skills/api-design

Install

npx -y skills add Roambee/claude-code-standards --skill api-design

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

2 things 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.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.1 KB, as published. Nobody here has run it

api-design

Use when designing or reviewing a new API endpoint in NestJS.

Announce at start: "Loading api-design standards."

URL Conventions

Versioning: /v1/ for stable, /v2/ for current generation. New endpoints start at /v1/.
Kebab-case: /v1/shipment-events, not /v1/shipmentEvents
Plural nouns for collections: /v1/shipments, not /v1/shipment
Nested resources for ownership: /v1/shipments/:id/events

Response Format

Always use ResponseHandlerService. Never call res.json() directly.

import { ResponseHandlerService } from '@decklar/platform-utility';

@Get()
async getShipments(@Query() query: GetShipmentsDto) {
  const result = await this.shipmentService.findAll(query);
  return this.responseHandler.success(result);
}

Paginated response shape:

{
  data: Shipment[],
  total: number,
  page: number,
  pageSize: number
}

Error response shape (handled by global exception filter — do not construct manually):

{
  statusCode: number,
  message: string,
  error: string
}

Auth Headers

All endpoints (except public health checks) require Authorization: Bearer <JWT>. The JWT is validated by the Central Authorization Service middleware — do not implement auth logic in individual services.

Swagger Documentation (Required)

Every endpoint must have:

@ApiTags('shipments')
@Controller('v1/shipments')
export class ShipmentsController {

  @Get()
  @ApiOperation({ summary: 'List all shipments with pagination' })
  @ApiResponse({ status: 200, description: 'Paginated shipment list', type: PaginatedShipmentDto })
  @ApiResponse({ status: 401, description: 'Unauthorized' })
  @ApiResponse({ status: 403, description: 'Forbidden' })
  async getShipments() { ... }
}

JSON Naming

Request and response bodies use camelCase:

{ "trackingNumber": "RB12345", "estimatedDelivery": "2026-06-10" }

Never use snake_case in JSON bodies (TypeORM entity columns can be snake_case internally — use @Column({ name: 'tracking_number' }) + a camelCase property name).