跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

api-design-patterns

REST API design, versioning, error responses, pagination, OpenAPI conventions. Use when designing new API endpoints, reviewing API contracts, or setting up Swagger/OpenAPI documentation.

sabahattink · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add sabahattink/antigravity-fullstack-hq --skill api-design-patterns

技能说明


name: api-design-patterns description: REST API design, versioning, error responses, pagination, OpenAPI conventions. Use when designing new API endpoints, reviewing API contracts, or setting up Swagger/OpenAPI documentation.

API Design Patterns

URL Structure

# Resource naming: plural nouns, lowercase, hyphenated
GET    /api/v1/users                    # list
POST   /api/v1/users                    # create
GET    /api/v1/users/:id                # read one
PATCH  /api/v1/users/:id                # partial update
PUT    /api/v1/users/:id                # full replace
DELETE /api/v1/users/:id                # delete

# Nested resources (max 2 levels)
GET    /api/v1/users/:userId/orders
POST   /api/v1/users/:userId/orders
GET    /api/v1/users/:userId/orders/:orderId

# Actions that don't fit CRUD — use verbs as sub-resources
POST   /api/v1/users/:id/activate
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/refresh
POST   /api/v1/auth/logout

Standard Response Envelope

// types/api-response.ts
export interface ApiResponse<T> {
  success: boolean
  data:    T | null
  error:   ApiError | null
  meta?:   ResponseMeta
}

export interface ApiError {
  code:    string   // machine-readable, stable: 'USER_NOT_FOUND'
  message: string   // human-readable
  details?: Record<string, string[]>  // field validation errors
}

export interface ResponseMeta {
  total:  number
  page:   number
  limit:  number
  pages:  number
}

// Success
{
  "success": true,
  "data": { "id": 1, "name": "Jane" },
  "error": null
}

// Error
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "email": ["Must be a valid email address"],
      "password": ["Must be at least 8 characters"]
    }
  }
}

// Paginated list
{
  "success": true,
  "data": [...],
  "error": null,
  "meta": { "total": 243, "page": 2, "limit": 20, "pages": 13 }
}

NestJS Response Interceptor

// common/interceptors/response-transform.interceptor.ts
import {
  Injectable, NestInterceptor, ExecutionContext, CallHandler,
} from '@nestjs/common'
import { Observable, map } from 'rxjs'
import { ApiResponse } from '../../types/api-response'

@Injectable()
export class ResponseTransformInterceptor<T> implements NestInterceptor<T, ApiResponse<T>> {
  intercept(context: ExecutionContext, next: CallHandler<T>): Observable<ApiResponse<T>> {
    return next.handle().pipe(
      map(data => ({
        success: true,
        data,
        error: null,
      }))
    )
  }
}

// Register globally in main.ts
app.useGlobalInterceptors(new ResponseTransformInterceptor())

HTTP Status Codes

// Use these — don't improvise
const STATUS_CODES = {
  // 2xx Success
  200: 'OK',                 // GET, PATCH, PUT — returned with data
  201: 'Created',            // POST — resource created
  204: 'No Content',         // DELETE, POST actions with no body

  // 3xx Redirect
  301: 'Moved Permanently',  // URL changed
  304: 'Not Modified',       // conditional GET, cache valid

  // 4xx Client Error
  400: 'Bad Request',        // malformed JSON, invalid params
  401: 'Unauthorized',       // not authenticated
  403: 'Forbidden',          // authenticated but not authorized
  404: 'Not Found',          // resource doesn't exist
  409: 'Conflict',           // duplicate email, version conflict
  422: 'Unprocessable',      // semantically invalid (business rule)
  429: 'Too Many Requests',  // rate limited

  // 5xx Server Error
  500: 'Internal Server Error', // unexpected exception
  502: 'Bad Gateway',           // upstream service error
  503: 'Service Unavailable',   // overloaded / maintenance
}

Pagination

// Query params: consistent naming
// GET /users?page=2&limit=20&sort=createdAt&order=desc

export class PaginationQueryDto {
  @IsOptional() @Type(() => Number) @IsInt() @Min(1)
  page: number = 1

  @IsOptional() @Type(() => Number) @IsInt() @Min(1) @Max(100)
  limit: number = 20

  @IsOptional() @IsString()
  sort?: string = 'createdAt'

  @IsOptional() @IsIn(['asc', 'desc'])
  order?: 'asc' | 'desc' = 'desc'

  @IsOptional() @IsString() @MaxLength(200)
  search?: string
}

// Response with cursor-based pagination (for feeds / infinite scroll)
export interface CursorPage<T> {
  data:       T[]
  nextCursor: string | null  // opaque, base64 encoded
  hasMore:    boolean
}

// Encode/decode cursor
function encodeCursor(payload: object): string {
  return Buffer.from(JSON.stringify(payload)).toString('base64url')
}
function decodeCursor(cursor: string): unknown {
  return JSON.parse(Buffer.from(cursor, 'base64url').toString())
}

API Versioning

// main.ts — URI versioning (recommended for breaking changes)
import { VersioningType } from '@nestjs/common'

app.enableVersioning({ type: VersioningType.URI })

// Controller
@Controller({ path: 'users', version: '1' })
export class UsersV1Controller { /* ... */ }

@Controller({ path: 'users', version: '2' })
export class UsersV2Controller { /* ... */ }

// Result: GET /v1/users, GET /v2/users

OpenAPI / Swagger Setup

// main.ts
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)

  const config = new DocumentBuilder()
    .setTitle('Example API')
    .setDescription('Backend API documentation')
    .setVersion('1.0')
    .addBearerAuth(
      { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
      'JWT'
    )
    .addServer('http://localhost:3000', 'Development')
    .addServer('https://api.example.com', 'Production')
    .build()

  const document = SwaggerModule.createDocument(app, config)
  SwaggerModule.setup('api/docs', app, document, {
    swaggerOptions: { persistAuthorization: true },
  })

  await app.listen(3000)
}
// Annotate DTOs and controllers
import 
阅读完整来源 ↗