E-commerce Docs
🔗 API Reference

API Endpoints

Complete API reference for all microservices endpoints

API Endpoints Reference

This section provides a comprehensive reference for all API endpoints across the e-commerce platform microservices. Each service exposes RESTful APIs for communication with client applications and other services.

🔧 Product Service API

Base URL: http://localhost:3001/api

Products

Get All Products

GET /products

Query Parameters:

  • page?: number - Page number (default: 1)
  • limit?: number - Items per page (default: 20)
  • category?: string - Filter by category slug
  • minPrice?: number - Minimum price filter
  • maxPrice?: number - Maximum price filter
  • sizes?: string - Comma-separated sizes filter
  • colors?: string - Comma-separated colors filter
  • search?: string - Search query
  • sortBy?: string - Sort field (name, price, createdAt)
  • sortOrder?: string - Sort order (asc, desc)

Response:

{
  products: Array<{
    id: number;
    name: string;
    shortDescription: string;
    description: string;
    price: number;
    sizes: string[];
    colors: string[];
    images: Record<string, string>;
    categorySlug: string;
    category: {
      id: number;
      name: string;
      slug: string;
    };
    createdAt: string;
    updatedAt: string;
  }>;
  totalCount: number;
  currentPage: number;
  totalPages: number;
  hasNextPage: boolean;
  hasPrevPage: boolean;
}

Get Product by ID

GET /products/:id

Response:

{
  id: number;
  name: string;
  shortDescription: string;
  description: string;
  price: number;
  sizes: string[];
  colors: string[];
  images: Record<string, string>;
  categorySlug: string;
  category: {
    id: number;
    name: string;
    slug: string;
  };
  createdAt: string;
  updatedAt: string;
}

Create Product

POST /products
Authorization: Bearer <token>

Request Body:

{
  name: string;
  shortDescription: string;
  description: string;
  price: number;
  categorySlug: string;
  sizes: string[];
  colors: string[];
  images: Record<string, string>;
}

Response: Created product object

Update Product

PUT /products/:id
Authorization: Bearer <token>

Request Body: Partial product data

Delete Product

DELETE /products/:id
Authorization: Bearer <token>

Categories

Get All Categories

GET /categories

Response:

[
  {
    id: number;
    name: string;
    slug: string;
    _count: {
      products: number;
    };
  }
]

Create Category

POST /categories
Authorization: Bearer <token>

Request Body:

{
  name: string;
  slug: string;
}

🛒 Order Service API

Base URL: http://localhost:3005/api

Orders

Get User Orders

GET /orders/user/:userId
Authorization: Bearer <token>

Query Parameters:

  • page?: number - Page number (default: 1)
  • limit?: number - Items per page (default: 10)
  • status?: string - Filter by status (success, failed)

Get Order by ID

GET /orders/:orderId
Authorization: Bearer <token>

Get All Orders (Admin)

GET /orders
Authorization: Bearer <admin-token>

Query Parameters:

  • page?: number, limit?: number - Pagination
  • status?: string - Filter by status
  • userId?: string - Filter by user
  • minAmount?: number, maxAmount?: number - Amount filters
  • startDate?: string, endDate?: string - Date filters
  • sortBy?: string, sortOrder?: string - Sorting

Analytics

Get Transaction Charts

GET /orders/analytics/charts
Authorization: Bearer <admin-token>

Query Parameters:

  • period?: string - Time period (6months, 1year, 2years)

Response:

{
  chartData: Array<{
    month: string;
    total: number;
    successful: number;
  }>;
  summary: {
    totalOrders: number;
    totalRevenue: number;
    averageOrderValue: number;
    successRate: number;
  };
}

Get Order Statistics

GET /orders/analytics/statistics
Authorization: Bearer <admin-token>

💳 Payment Service API

Base URL: http://localhost:3006/api

Checkout Sessions

Create Checkout Session

POST /payments/create-checkout-session

Request Body:

{
  products: Array<{
    name: string;
    price: number;
    quantity: number;
    image?: string;
  }>;
  successUrl: string;
  cancelUrl: string;
  customerEmail?: string;
  metadata?: Record<string, string>;
}

Response:

{
  sessionId: string;
  url: string;
}

Verify Product Prices

POST /payments/verify-prices

Request Body:

{
  products: Array<{
    productId: string;
    price: number;
    quantity: number;
  }>;
}

Response:

{
  verified: boolean;
  discrepancies?: Array<{
    productId: string;
    expectedPrice: number;
    providedPrice: number;
  }>;
}

Webhooks

Stripe Webhook Handler

POST /payments/webhooks/stripe

Headers:

Content-Type: application/json
Stripe-Signature: t=123,v1=signature

🔐 Authentication Service API

Base URL: http://localhost:3007/api

Users

Get All Users

GET /users
Authorization: Bearer <admin-token>

Query Parameters:

  • page?: number, limit?: number - Pagination
  • search?: string - Search query
  • role?: string - Filter by role

Get User by ID

GET /users/:userId
Authorization: Bearer <token>

Create User

POST /users

Request Body:

{
  firstName: string;
  lastName: string;
  username: string;
  emailAddress: string[];
  password: string;
}

Update User

PUT /users/:userId
Authorization: Bearer <token>

Delete User

DELETE /users/:userId
Authorization: Bearer <admin-token>

📧 Email Service API

Base URL: http://localhost:3008/api

The Email Service primarily consumes Kafka events and doesn't expose many HTTP endpoints. It processes email events and sends transactional emails.

Health Check

GET /health

Response:

{
  status: string;
  timestamp: string;
  kafka: {
    connected: boolean;
    topics: string[];
  };
}

🔗 Service Communication

Inter-Service Communication

Services communicate with each other using direct HTTP calls for synchronous operations:

Client App → Product Service

// Fetch products
const response = await fetch('http://localhost:3001/api/products');
const products = await response.json();

Client App → Payment Service

// Create checkout session
const response = await fetch('http://localhost:3006/api/payments/create-checkout-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(checkoutData),
});

Admin Panel → Order Service

// Fetch orders for admin
const response = await fetch('http://localhost:3005/api/orders', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});

Authentication Headers

Most service endpoints require authentication:

const headers = {
  'Authorization': `Bearer ${jwtToken}`,
  'Content-Type': 'application/json',
};

// For admin operations
const adminHeaders = {
  'Authorization': `Bearer ${adminJwtToken}`,
  'Content-Type': 'application/json',
};

🚨 Error Responses

Standard Error Format

{
  error: string;
  message: string;
  details?: any;
  timestamp: string;
}

Common HTTP Status Codes

200 - Success

Standard success response

201 - Created

Resource successfully created

400 - Bad Request

Invalid request data or validation errors

401 - Unauthorized

Missing or invalid authentication token

403 - Forbidden

Access denied (insufficient permissions)

404 - Not Found

Resource not found

422 - Unprocessable Entity

Validation errors in request data

500 - Internal Server Error

Server-side error

Validation Error Example

{
  error: "Validation Error",
  message: "Request validation failed",
  details: [
    {
      field: "name",
      message: "Product name is required!"
    },
    {
      field: "price",
      message: "Price must be greater than 0"
    }
  ],
  timestamp: "2024-01-01T12:00:00Z"
}

🔒 Authentication

JWT Token Format

// Token payload
{
  sub: "user_id",
  email: "user@example.com",
  role: "user|admin",
  iat: 1234567890,
  exp: 1234567890
}

Token Validation

Services validate JWT tokens from Clerk:

// Middleware example
const authenticateToken = async (req: Request, res: Response) => {
  const authHeader = req.headers['authorization'];
  const token = authHeader?.split(' ')[1];

  if (!token) {
    return res.status(401).json({ error: 'Access token required' });
  }

  try {
    const payload = await clerk.verifyToken(token);
    req.user = payload;
  } catch (error) {
    return res.status(403).json({ error: 'Invalid token' });
  }
};

📊 Response Formats

Paginated Response

{
  data: Array<any>;
  totalCount: number;
  currentPage: number;
  totalPages: number;
  hasNextPage: boolean;
  hasPrevPage: boolean;
}

Product Response

{
  id: number;
  name: string;
  shortDescription: string;
  description: string;
  price: number;
  sizes: string[];
  colors: string[];
  images: Record<string, string>;
  categorySlug: string;
  category: {
    id: number;
    name: string;
    slug: string;
  };
  createdAt: string;
  updatedAt: string;
}

Order Response

{
  _id: string;
  userId: string;
  email: string;
  amount: number;
  status: 'success' | 'failed';
  products: Array<{
    name: string;
    quantity: number;
    price: number;
  }>;
  createdAt: string;
  updatedAt: string;
}

🧪 Testing API Endpoints

Using cURL

Get Products

curl -X GET "http://localhost:3001/api/products?page=1&limit=10" \
  -H "Content-Type: application/json"

Create Product (Admin)

curl -X POST "http://localhost:3001/api/products" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "name": "Test Product",
    "shortDescription": "A test product",
    "description": "Detailed description",
    "price": 29.99,
    "categorySlug": "test-category",
    "sizes": ["M", "L"],
    "colors": ["red", "blue"],
    "images": {
      "red": "red.jpg",
      "blue": "blue.jpg"
    }
  }'

Create Checkout Session

curl -X POST "http://localhost:3006/api/payments/create-checkout-session" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "name": "Test Product",
        "price": 29.99,
        "quantity": 1
      }
    ],
    "successUrl": "http://localhost:3002/success",
    "cancelUrl": "http://localhost:3002/cart"
  }'

Using Thunder Client (VS Code)

  1. Install Thunder Client extension
  2. Create new request
  3. Set method and URL
  4. Add headers and body
  5. Send request

Postman Collection

Import this JSON for a complete API collection:

{
  "info": {
    "name": "E-commerce API Collection",
    "description": "Complete API collection for e-commerce platform"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "http://localhost:3001"
    }
  ],
  "item": [
    {
      "name": "Products",
      "item": [
        {
          "name": "Get All Products",
          "request": {
            "method": "GET",
            "url": "{{base_url}}/api/products",
            "header": []
          }
        }
      ]
    }
  ]
}

🔍 API Health Checks

Service Health Endpoints

Product Service Health

GET /api/health

Order Service Health

GET /api/health

Payment Service Health

GET /api/health

Auth Service Health

GET /api/health

Health Response Format

{
  status: "healthy" | "unhealthy";
  timestamp: string;
  uptime: number;
  version: string;
  database: {
    connected: boolean;
    latency: number;
  };
  kafka: {
    connected: boolean;
    topics: string[];
  };
}

🚀 Rate Limiting

Default Limits

  • General endpoints: 100 requests per minute
  • Admin endpoints: 1000 requests per minute
  • Payment endpoints: 50 requests per minute

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200

Rate Limited Response

HTTP 429 Too Many Requests

{
  error: "Rate limit exceeded",
  message: "Too many requests",
  retryAfter: 60
}

📈 API Versioning

Current API version: v1

Version Header

API-Version: v1

URL Versioning (Future)

/api/v1/products
/api/v2/products

🔮 Future API Enhancements

Planned Endpoints

Product Reviews API

GET    /api/products/:id/reviews
POST   /api/products/:id/reviews
PUT    /api/products/:id/reviews/:reviewId
DELETE /api/products/:id/reviews/:reviewId

Inventory API

GET    /api/inventory
PUT    /api/inventory/:productId
GET    /api/inventory/low-stock

Analytics API

GET    /api/analytics/sales
GET    /api/analytics/customers
GET    /api/analytics/products

WebSocket Support

Real-time API updates for live data:

// WebSocket connection for real-time updates
const ws = new WebSocket('ws://localhost:3001/api/events');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Real-time update:', data);
};

GraphQL API (Future)

query GetProducts($category: String) {
  products(category: $category) {
    id
    name
    price
    category {
      name
    }
  }
}

Development Setup

Complete guide to set up the development environment for the e-commerce platform

On this page

API Endpoints Reference🔧 Product Service APIProductsGet All ProductsGet Product by IDCreate ProductUpdate ProductDelete ProductCategoriesGet All CategoriesCreate Category🛒 Order Service APIOrdersGet User OrdersGet Order by IDGet All Orders (Admin)AnalyticsGet Transaction ChartsGet Order Statistics💳 Payment Service APICheckout SessionsCreate Checkout SessionVerify Product PricesWebhooksStripe Webhook Handler🔐 Authentication Service APIUsersGet All UsersGet User by IDCreate UserUpdate UserDelete User📧 Email Service APIHealth Check🔗 Service CommunicationInter-Service CommunicationClient App → Product ServiceClient App → Payment ServiceAdmin Panel → Order ServiceAuthentication Headers🚨 Error ResponsesStandard Error FormatCommon HTTP Status Codes200 - Success201 - Created400 - Bad Request401 - Unauthorized403 - Forbidden404 - Not Found422 - Unprocessable Entity500 - Internal Server ErrorValidation Error Example🔒 AuthenticationJWT Token FormatToken Validation📊 Response FormatsPaginated ResponseProduct ResponseOrder Response🧪 Testing API EndpointsUsing cURLGet ProductsCreate Product (Admin)Create Checkout SessionUsing Thunder Client (VS Code)Postman Collection🔍 API Health ChecksService Health EndpointsProduct Service HealthOrder Service HealthPayment Service HealthAuth Service HealthHealth Response Format🚀 Rate LimitingDefault LimitsRate Limit HeadersRate Limited Response📈 API VersioningVersion HeaderURL Versioning (Future)🔮 Future API EnhancementsPlanned EndpointsProduct Reviews APIInventory APIAnalytics APIWebSocket SupportGraphQL API (Future)