Part 4: API Development and Integrations

Introduction

APIs are the backbone of modern software. In this part, I'll show you how I build production-ready APIs and integrate with external services using the Model Context Protocol (MCP).

We'll build a complete API for the POS system mentioned in Part 1, with MCP integration for AI-powered features.

API Design Principles

RESTful API Structure

The POS API Endpoints

// src/api/routes.ts
import { FastifyInstance } from 'fastify';

export async function registerRoutes(app: FastifyInstance) {
  // Health check (no auth)
  app.get('/health', healthController.check);

  // Authentication
  app.post('/auth/login', authController.login);
  app.post('/auth/refresh', authController.refresh);

  // Products (requires auth)
  app.register(async (authenticated) => {
    authenticated.addHook('onRequest', authMiddleware);

    // CRUD operations
    authenticated.get('/products', productController.list);
    authenticated.get('/products/:id', productController.get);
    authenticated.post('/products', productController.create);
    authenticated.put('/products/:id', productController.update);
    authenticated.delete('/products/:id', productController.delete);

    // Bulk operations
    authenticated.post('/products/bulk', productController.bulkCreate);
    authenticated.put('/products/bulk', productController.bulkUpdate);
  });

  // Orders
  app.register(async (authenticated) => {
    authenticated.addHook('onRequest', authMiddleware);

    authenticated.get('/orders', orderController.list);
    authenticated.get('/orders/:id', orderController.get);
    authenticated.post('/orders', orderController.create);
    authenticated.put('/orders/:id/status', orderController.updateStatus);
    authenticated.post('/orders/:id/cancel', orderController.cancel);
    authenticated.get('/orders/:id/receipt', orderController.getReceipt);
  });

  // Analytics (requires admin role)
  app.register(async (admin) => {
    admin.addHook('onRequest', authMiddleware);
    admin.addHook('onRequest', requireRole('admin'));

    admin.get('/analytics/sales', analyticsController.sales);
    admin.get('/analytics/products', analyticsController.topProducts);
    admin.get('/analytics/revenue', analyticsController.revenue);
  });

  // MCP Integration - AI Features
  app.register(async (mcp) => {
    mcp.addHook('onRequest', authMiddleware);

    mcp.post('/ai/analyze-sales', mcpController.analyzeSales);
    mcp.post('/ai/forecast', mcpController.forecastDemand);
    mcp.post('/ai/recommendations', mcpController.productRecommendations);
  });
}

Implementing the Product API

The Controller Layer

// src/controllers/productController.ts
import { FastifyRequest, FastifyReply } from 'fastify';
import { ProductService } from '../services/productService';
import { CreateProductSchema, UpdateProductSchema } from '../schemas/product';
import { z } from 'zod';

export class ProductController {
  constructor(private productService: ProductService) {}

  async list(request: FastifyRequest, reply: FastifyReply) {
    const { page = 1, limit = 20, category, search } = request.query as {
      page?: number;
      limit?: number;
      category?: string;
      search?: string;
    };

    // Validate pagination
    if (page < 1 || limit < 1 || limit > 100) {
      return reply.code(400).send({
        error: 'Invalid pagination parameters',
      });
    }

    const result = await this.productService.listProducts({
      page,
      limit,
      category,
      search,
      tenantId: request.user.tenantId, // Multi-tenant isolation
    });

    return reply.send({
      data: result.products,
      pagination: {
        page,
        limit,
        total: result.total,
        totalPages: Math.ceil(result.total / limit),
      },
    });
  }

  async get(request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) {
    const { id } = request.params;

    const product = await this.productService.getProduct(id, request.user.tenantId);

    if (!product) {
      return reply.code(404).send({
        error: 'Product not found',
      });
    }

    return reply.send({ data: product });
  }

  async create(request: FastifyRequest, reply: FastifyReply) {
    try {
      // Validate request body
      const data = CreateProductSchema.parse(request.body);

      // Create product
      const product = await this.productService.createProduct({
        ...data,
        tenantId: request.user.tenantId,
        createdBy: request.user.id,
      });

      return reply.code(201).send({ data: product });
    } catch (error) {
      if (error instanceof z.ZodError) {
        return reply.code(400).send({
          error: 'Validation failed',
          details: error.errors,
        });
      }
      throw error;
    }
  }

  async update(
    request: FastifyRequest<{ Params: { id: string } }>,
    reply: FastifyReply
  ) {
    try {
      const { id } = request.params;
      const data = UpdateProductSchema.parse(request.body);

      const product = await this.productService.updateProduct(
        id,
        request.user.tenantId,
        {
          ...data,
          updatedBy: request.user.id,
        }
      );

      if (!product) {
        return reply.code(404).send({ error: 'Product not found' });
      }

      return reply.send({ data: product });
    } catch (error) {
      if (error instanceof z.ZodError) {
        return reply.code(400).send({
          error: 'Validation failed',
          details: error.errors,
        });
      }
      throw error;
    }
  }

  async delete(
    request: FastifyRequest<{ Params: { id: string } }>,
    reply: FastifyReply
  ) {
    const { id } = request.params;

    // Soft delete
    await this.productService.deleteProduct(id, request.user.tenantId);

    return reply.code(204).send();
  }

  async bulkCreate(request: FastifyRequest, reply: FastifyReply) {
    const products = z.array(CreateProductSchema).parse(request.body);

    if (products.length > 100) {
      return reply.code(400).send({
        error: 'Maximum 100 products per bulk operation',
      });
    }

    const result = await this.productService.bulkCreateProducts(
      products.map(p => ({
        ...p,
        tenantId: request.user.tenantId,
        createdBy: request.user.id,
      }))
    );

    return reply.code(201).send({
      data: result.products,
      summary: {
        total: products.length,
        created: result.created,
        failed: result.failed,
        errors: result.errors,
      },
    });
  }
}

The Service Layer

// src/services/productService.ts
import { PrismaClient } from '@prisma/client';
import { logger } from '../utils/logger';
import { Redis } from 'ioredis';

export class ProductService {
  constructor(
    private db: PrismaClient,
    private cache: Redis
  ) {}

  async listProducts(params: {
    page: number;
    limit: number;
    category?: string;
    search?: string;
    tenantId: string;
  }) {
    const { page, limit, category, search, tenantId } = params;
    const skip = (page - 1) * limit;

    // Build cache key
    const cacheKey = `products:${tenantId}:page=${page}:limit=${limit}:category=${category || 'all'}:search=${search || ''}`;

    // Try cache first
    const cached = await this.cache.get(cacheKey);
    if (cached) {
      logger.debug('Products cache hit', { cacheKey });
      return JSON.parse(cached);
    }

    // Build query
    const where = {
      tenantId,
      deletedAt: null,
      ...(category && { category }),
      ...(search && {
        OR: [
          { name: { contains: search, mode: 'insensitive' } },
          { description: { contains: search, mode: 'insensitive' } },
          { sku: { contains: search, mode: 'insensitive' } },
        ],
      }),
    };

    // Execute query
    const [products, total] = await Promise.all([
      this.db.product.findMany({
        where,
        skip,
        take: limit,
        orderBy: { createdAt: 'desc' },
        include: {
          category: true,
          inventory: true,
        },
      }),
      this.db.product.count({ where }),
    ]);

    const result = { products, total };

    // Cache for 5 minutes
    await this.cache.setex(cacheKey, 300, JSON.stringify(result));

    return result;
  }

  async getProduct(id: string, tenantId: string) {
    const cacheKey = `product:${id}`;

    // Try cache
    const cached = await this.cache.get(cacheKey);
    if (cached) {
      return JSON.parse(cached);
    }

    // Fetch from DB
    const product = await this.db.product.findFirst({
      where: {
        id,
        tenantId,
        deletedAt: null,
      },
      include: {
        category: true,
        inventory: true,
        priceHistory: {
          orderBy: { createdAt: 'desc' },
          take: 10,
        },
      },
    });

    if (product) {
      await this.cache.setex(cacheKey, 300, JSON.stringify(product));
    }

    return product;
  }

  async createProduct(data: CreateProductInput) {
    // Start transaction
    const product = await this.db.$transaction(async (tx) => {
      // Create product
      const newProduct = await tx.product.create({
        data: {
          name: data.name,
          description: data.description,
          sku: data.sku,
          price: data.price,
          categoryId: data.categoryId,
          tenantId: data.tenantId,
          createdBy: data.createdBy,
        },
      });

      // Initialize inventory
      await tx.inventory.create({
        data: {
          productId: newProduct.id,
          quantity: data.initialQuantity || 0,
          tenantId: data.tenantId,
        },
      });

      // Create price history entry
      await tx.priceHistory.create({
        data: {
          productId: newProduct.id,
          price: data.price,
          changedBy: data.createdBy,
          tenantId: data.tenantId,
        },
      });

      return newProduct;
    });

    // Invalidate cache
    await this.invalidateProductCache(data.tenantId);

    logger.info('Product created', {
      productId: product.id,
      tenantId: data.tenantId,
    });

    return product;
  }

  async updateProduct(id: string, tenantId: string, data: UpdateProductInput) {
    const product = await this.db.product.update({
      where: {
        id,
        tenantId,
        deletedAt: null,
      },
      data: {
        ...data,
        updatedAt: new Date(),
      },
    });

    // Invalidate caches
    await Promise.all([
      this.cache.del(`product:${id}`),
      this.invalidateProductCache(tenantId),
    ]);

    // If price changed, create price history entry
    if (data.price) {
      await this.db.priceHistory.create({
        data: {
          productId: id,
          price: data.price,
          changedBy: data.updatedBy,
          tenantId,
        },
      });
    }

    return product;
  }

  async deleteProduct(id: string, tenantId: string) {
    // Soft delete
    await this.db.product.update({
      where: { id, tenantId },
      data: { deletedAt: new Date() },
    });

    await Promise.all([
      this.cache.del(`product:${id}`),
      this.invalidateProductCache(tenantId),
    ]);
  }

  private async invalidateProductCache(tenantId: string) {
    // Delete all product list caches for this tenant
    const pattern = `products:${tenantId}:*`;
    const keys = await this.cache.keys(pattern);
    if (keys.length > 0) {
      await this.cache.del(...keys);
    }
  }

  async bulkCreateProducts(products: CreateProductInput[]) {
    const results = {
      products: [],
      created: 0,
      failed: 0,
      errors: [],
    };

    for (const productData of products) {
      try {
        const product = await this.createProduct(productData);
        results.products.push(product);
        results.created++;
      } catch (error) {
        results.failed++;
        results.errors.push({
          sku: productData.sku,
          error: error instanceof Error ? error.message : 'Unknown error',
        });
        logger.error('Bulk product creation failed', {
          sku: productData.sku,
          error,
        });
      }
    }

    return results;
  }
}

Model Context Protocol (MCP) Integration

MCP allows AI assistants to interact with your application. Here's how I integrated it.

MCP Server Implementation

// src/mcp/server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import { ProductService } from '../services/productService';
import { AnalyticsService } from '../services/analyticsService';

export class POSMCPServer {
  private server: Server;

  constructor(
    private productService: ProductService,
    private analyticsService: AnalyticsService
  ) {
    this.server = new Server(
      {
        name: 'pos-system-mcp',
        version: '1.0.0',
      },
      {
        capabilities: {
          tools: {},
        },
      }
    );

    this.setupHandlers();
  }

  private setupHandlers() {
    // List available tools
    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: [
        {
          name: 'get_product',
          description: 'Retrieve product details by ID or SKU',
          inputSchema: {
            type: 'object',
            properties: {
              identifier: {<br/>                type: 'string',
                description: 'Product ID or SKU',
              },
              tenantId: {
                type: 'string',
                description: 'Tenant ID for multi-tenant isolation',
              },
            },
            required: ['identifier', 'tenantId'],
          },
        },
        {
          name: 'search_products',
          description: 'Search products by name, description, or SKU',
          inputSchema: {
            type: 'object',
            properties: {
              query: {
                type: 'string',
                description: 'Search query',
              },
              tenantId: {
                type: 'string',
              },
              limit: {
                type: 'number',
                description: 'Maximum results (default: 10)',
                default: 10,
              },
            },
            required: ['query', 'tenantId'],
          },
        },
        {
          name: 'analyze_sales',
          description: 'Analyze sales data for a given period',
          inputSchema: {
            type: 'object',
            properties: {
              tenantId: {
                type: 'string',
              },
              startDate: {
                type: 'string',
                format: 'date-time',
              },
              endDate: {
                type: 'string',
                format: 'date-time',
              },
              groupBy: {
                type: 'string',
                enum: ['day', 'week', 'month'],
                default: 'day',
              },
            },
            required: ['tenantId', 'startDate', 'endDate'],
          },
        },
        {
          name: 'forecast_demand',
          description: 'Forecast product demand using historical data',
          inputSchema: {
            type: 'object',
            properties: {
              productId: {
                type: 'string',
              },
              tenantId: {
                type: 'string',
              },
              daysAhead: {
                type: 'number',
                description: 'Number of days to forecast',
                default: 30,
              },
            },
            required: ['productId', 'tenantId'],
          },
        },
      ],
    }));

    // Handle tool calls
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      switch (name) {
        case 'get_product':
          return this.handleGetProduct(args);
        case 'search_products':
          return this.handleSearchProducts(args);
        case 'analyze_sales':
          return this.handleAnalyzeSales(args);
        case 'forecast_demand':
          return this.handleForecastDemand(args);
        default:
          throw new Error(`Unknown tool: ${name}`);
      }
    });
  }

  private async handleGetProduct(args: any) {
    const { identifier, tenantId } = args;

    // Try by ID first, then by SKU
    let product = await this.productService.getProduct(identifier, tenantId);

    if (!product) {
      product = await this.productService.getProductBySKU(identifier, tenantId);
    }

    if (!product) {
      return {
        content: [
          {
            type: 'text',
            text: `Product not found: ${identifier}`,
          },
        ],
      };
    }

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              id: product.id,
              name: product.name,
              sku: product.sku,
              price: product.price,
              category: product.category?.name,
              inventory: product.inventory?.quantity,
              description: product.description,
            },
            null,
            2
          ),
        },
      ],
    };
  }

  private async handleSearchProducts(args: any) {
    const { query, tenantId, limit = 10 } = args;

    const results = await this.productService.listProducts({
      page: 1,
      limit,
      search: query,
      tenantId,
    });

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              total: results.total,
              products: results.products.map(p => ({
                id: p.id,
                name: p.name,
                sku: p.sku,
                price: p.price,
                stock: p.inventory?.quantity,
              })),
            },
            null,
            2
          ),
        },
      ],
    };
  }

  private async handleAnalyzeSales(args: any) {
    const { tenantId, startDate, endDate, groupBy = 'day' } = args;

    const analysis = await this.analyticsService.analyzeSales({
      tenantId,
      startDate: new Date(startDate),
      endDate: new Date(endDate),
      groupBy,
    });

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(analysis, null, 2),
        },
      ],
    };
  }

  private async handleForecastDemand(args: any) {
    const { productId, tenantId, daysAhead = 30 } = args;

    const forecast = await this.analyticsService.forecastDemand({
      productId,
      tenantId,
      daysAhead,
    });

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(forecast, null, 2),
        },
      ],
    };
  }

  async start() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error('POS MCP Server running on stdio');
  }
}

MCP Configuration

// mcp-config.json
{
  "mcpServers": {
    "pos-system": {
      "command": "node",
      "args": ["dist/mcp/server.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/pos",
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

Using MCP from VS Code Copilot

Once configured, I can ask Copilot:

Me: "What are the top 5 selling products this month?"

Copilot (uses MCP tool):

Using tool: analyze_sales
Parameters: {
  tenantId: "tenant_123",
  startDate: "2024-01-01",
  endDate: "2024-01-31",
  groupBy: "product"
}

Results:
1. Cappuccino - $5,234 (234 sales)
2. Croissant - $3,122 (412 sales)
3. Latte - $2,988 (166 sales)
4. Espresso - $2,456 (345 sales)
5. Muffin - $1,877 (289 sales)

Me: "Forecast demand for Cappuccino for next month"

Copilot:

Using tool: forecast_demand
Parameters: {
  productId: "prod_cappuccino_123",
  tenantId: "tenant_123",
  daysAhead: 30
}

Forecast:
- Expected sales: 280 units
- Predicted revenue: $6,300
- Confidence: 85%
- Recommendation: Stock 300+ units to handle peak demand

API Documentation

OpenAPI/Swagger

// src/config/swagger.ts
import { FastifyInstance } from 'fastify';
import fastifySwagger from '@fastify/swagger';
import fastifySwaggerUi from '@fastify/swagger-ui';

export async function setupSwagger(app: FastifyInstance) {
  await app.register(fastifySwagger, {
    swagger: {
      info: {
        title: 'POS System API',
        description: 'Multi-tenant Point of Sale System API',
        version: '1.0.0',
      },
      host: process.env.API_HOST || 'localhost:3000',
      schemes: ['http', 'https'],
      consumes: ['application/json'],
      produces: ['application/json'],
      tags: [
        { name: 'auth', description: 'Authentication endpoints' },
        { name: 'products', description: 'Product management' },
        { name: 'orders', description: 'Order management' },
        { name: 'analytics', description: 'Analytics and reporting' },
      ],
      securityDefinitions: {
        Bearer: {
          type: 'apiKey',
          name: 'Authorization',
          in: 'header',
        },
      },
    },
  });

  await app.register(fastifySwaggerUi, {
    routePrefix: '/docs',
    uiConfig: {
      docExpansion: 'list',
      deepLinking: false,
    },
  });
}

Access docs at: http://localhost:3000/docs

API Versioning

URL-based Versioning

// src/api/v1/routes.ts
export async function v1Routes(app: FastifyInstance) {
  app.register(productRoutes, { prefix: '/v1' });
  app.register(orderRoutes, { prefix: '/v1' });
}

// src/api/v2/routes.ts
export async function v2Routes(app: FastifyInstance) {
  // v2 has breaking changes (different response format)
  app.register(productRoutesV2, { prefix: '/v2' });
  app.register(orderRoutesV2, { prefix: '/v2' });
}

// Access:
// GET /v1/products - old format
// GET /v2/products - new format

Rate Limiting

// src/middleware/rateLimiter.ts
import rateLimit from '@fastify/rate-limit';

app.register(rateLimit, {
  max: 100, // 100 requests
  timeWindow: '15 minutes',
  redis: redisClient, // Share limits across instances
  keyGenerator: (request) => {
    // Rate limit by API key or IP
    return request.headers['x-api-key'] || request.ip;
  },
  errorResponseBuilder: (request, context) => ({
    statusCode: 429,
    error: 'Too Many Requests',
    message: `Rate limit exceeded. Retry after ${context.after}`,
  }),
});

Key Takeaways

1. Layer your API: Controller → Service → Data Layer

2. Use caching: Redis significantly reduces DB load

3. Implement MCP: Let AI interact with your app

4. Document everything: OpenAPI/Swagger is essential

5. Version your API: Breaking changes need new versions

6. Rate limit: Protect your API from abuse

What's Next

In Part 5, we'll deploy this API:

• Docker containerization

• CI/CD pipeline setup

• Kubernetes deployment

• Security hardening

• Monitoring and alerting

---

APIs are contracts. Make them reliable, well-documented, and versioned. See you in Part 5.