API Standards

Response Envelope

// All successful responses follow this format
interface SuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    pagination?: PaginationMeta;
    [key: string]: unknown;
  };
}

interface PaginationMeta {
  total: number;
  page: number;
  pageSize: number;
  totalPages: number;
  hasNext: boolean;
  hasPrevious: boolean;
}

Examples

Single item

{
  "success": true,
  "data": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

List with pagination

{
  "success": true,
  "data": [
    { "id": "uuid1", "name": "Product 1" },
    { "id": "uuid2", "name": "Product 2" }
  ],
  "meta": {
    "pagination": {
      "total": 100,
      "page": 1,
      "pageSize": 20,
      "totalPages": 5,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}

---

Pagination

// Offset pagination with query params: ?page=1&pageSize=20

interface PaginationQuery {
  page?: number;      // Default: 1, min: 1
  pageSize?: number;  // Default: 20, max: 100
}

// Controller usage
@Get()
async findAll(
  @Query() pagination: PaginationQuery,
): Promise<SuccessResponse<Product[]>> {
  const { page = 1, pageSize = 20 } = pagination;
  const result = await this.productService.findAll({ page, pageSize });

  return {
    success: true,
    data: result.items,
    meta: { pagination: result.pagination },
  };
}

---

Filtering and Sorting

// Query params for filtering
// GET /api/v1/products?status=ACTIVE&categoryId=uuid&minPrice=100&maxPrice=500

// Query params for sorting
// GET /api/v1/products?sortBy=price&sortOrder=asc

interface ProductFilterQuery {
  status?: ProductStatus;
  categoryId?: string;
  minPrice?: number;
  maxPrice?: number;
  search?: string;       // Full-text search on name/description
  sortBy?: 'price' | 'name' | 'createdAt';
  sortOrder?: 'asc' | 'desc';
}

---

API Versioning

/api/v1/...  ← Current version

Future:
/api/v2/...  ← Major breaking changes only

Strategy: URL-based versioning (simplest). Only create v2 when breaking changes are unavoidable.

---

API Documentation (Scalar)

Interactive API documentation using Scalar — a modern alternative to Swagger UI with better UX, dark mode, and faster rendering.

Installation

npm install @nestjs/swagger @scalar/nestjs-api-reference

Setup

// main.ts
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { apiReference } from '@scalar/nestjs-api-reference';

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

  // OpenAPI specification
  const config = new DocumentBuilder()
    .setTitle('IWM Platform API')
    .setDescription('MLM Platform with Investment and Product Marketplaces')
    .setVersion('1.0')
    .addBearerAuth()
    .addTag('auth', 'Authentication endpoints')
    .addTag('users', 'User management')
    .addTag('mlm', 'MLM/Partner operations')
    .addTag('products', 'E-commerce products')
    .addTag('orders', 'Order management')
    .addTag('investments', 'Investment operations')
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // Scalar UI at /api/docs (replaces Swagger UI)
  app.use('/api/docs', apiReference({
    spec: { content: document },
    theme: 'purple',  // or 'default', 'moon', 'mars'
  }));

  // Optional: JSON spec endpoint for external tools
  app.use('/api/docs/openapi.json', (req, res) => res.json(document));

  await app.listen(3000);
}

Features

Feature	Description
Try It	Interactive request builder with auth support
Search	Full-text search across all endpoints
Dark Mode	Built-in theme switching
Code Samples	Auto-generated examples in multiple languages
OpenAPI 3.1	Full specification support

Access

• Interactive Docs: http://localhost:3000/api/docs
• OpenAPI JSON: http://localhost:3000/api/docs/openapi.json

---

Related Documents

• Error Handling
• API Structure