Endpoint

Endpoint Generator

This skill helps you create new API endpoints following the Express.js MVC pattern used in this codebase.

Instructions

When the user invokes this skill, guide them through creating a new endpoint:

1. Ask for endpoint details:

   • Feature name (e.g., "notifications", "settings", "reports")
   • Route path (e.g., "/api/notifications")
   • HTTP methods needed (GET, POST, PUT, DELETE, PATCH)
   • Authentication requirements (none, authenticate, requireAdmin)
   • Brief description of what each endpoint does

2. Create the route file:

   • Location: /home/user/math/backend/src/routes/[featureName]Routes.ts
   • Import necessary dependencies (Router, middleware, controllers)
   • Define routes with appropriate HTTP methods
   • Apply middleware (authenticate, requireAdmin, etc.)
   • Export the router

3. Create the controller file:

   • Location: /home/user/math/backend/src/controllers/[featureName]Controller.ts
   • Import Request, Response types from Express
   • Create controller functions for each endpoint
   • Include proper error handling with try-catch
   • Validate request inputs
   • Return appropriate HTTP status codes
   • Export all controller functions

4. Optionally create a service file if needed:

   • Location: /home/user/math/backend/src/services/[featureName]Service.ts
   • Contains business logic and external integrations
   • Separates data processing from HTTP handling
   • Export service functions

5. Show registration instructions:

   • Provide the exact line to add to /home/user/math/backend/src/index.ts
   • Show where to add the import statement
   • Show where to register the route with app.use()

Patterns to Follow

Route File Pattern

import { Router } from 'express';
import { authenticate, requireAdmin } from '../middleware/auth';
import {
  controllerFunction1,
  controllerFunction2,
} from '../controllers/[featureName]Controller';

const router = Router();

/**
 * @route   GET /api/[feature]/[path]
 * @desc    Description of what this endpoint does
 * @access  Public/Private/Admin
 */
router.get('/[path]', authenticate, controllerFunction1);

/**
 * @route   POST /api/[feature]/[path]
 * @desc    Description of what this endpoint does
 * @access  Public/Private/Admin
 */
router.post('/[path]', authenticate, requireAdmin, controllerFunction2);

export default router;

Controller File Pattern

import { Request, Response } from 'express';
import { serviceFunction } from '../services/[featureName]Service';

/**
 * Controller for [description]
 */
export const controllerFunction1 = async (req: Request, res: Response) => {
  try {
    // Extract parameters
    const { param1, param2 } = req.body;
    const userId = req.user?.userId;

    // Validate inputs
    if (!param1) {
      return res.status(400).json({
        success: false,
        error: 'param1 is required',
      });
    }

    // Call service layer
    const result = await serviceFunction(param1, param2, userId);

    // Return success response
    return res.status(200).json({
      success: true,
      data: result,
    });
  } catch (error: any) {
    console.error('Error in controllerFunction1:', error);
    return res.status(500).json({
      success: false,
      error: error.message || 'Internal server error',
    });
  }
};

Service File Pattern (Optional)

/**
 * Service function for [description]
 */
export async function serviceFunction(
  param1: string,
  param2?: string,
  userId?: string
): Promise<any> {
  // Business logic here
  // Database queries
  // External API calls
  // Data processing

  return result;
}

Middleware Options

• authenticate - Requires valid JWT token, attaches req.user
• requireAdmin - Requires admin role (must use after authenticate)
• No middleware - Public endpoint

Error Handling Standards

• 400 - Bad Request (validation errors)
• 401 - Unauthorized (authentication required)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found
• 500 - Internal Server Error

Response Format Standards

Success responses:

{
  success: true,
  data: result
}

Error responses:

{
  success: false,
  error: 'Error message'
}

Registration Instructions Template

After creating the files, provide these instructions:

1. Add import to /home/user/math/backend/src/index.ts:

   import [featureName]Routes from './routes/[featureName]Routes';
   

2. Register route (add after existing routes):

   app.use('/api/[feature]', [featureName]Routes);
   

Tips

• Use descriptive function and variable names
• Add JSDoc comments for documentation
• Keep controllers thin - move complex logic to services
• Always validate user inputs
• Use appropriate HTTP status codes
• Log errors with descriptive messages
• Consider adding TypeScript interfaces for request/response types
• Test with different authentication scenarios

Examples

Example 1: Simple GET endpoint

User request: "Create an endpoint to get user profile"

Steps:

1. Create profileRoutes.ts with GET /api/profile route
2. Create profileController.ts with getProfile function
3. Add authentication middleware
4. Register route in index.ts

Example 2: Full CRUD resource

User request: "Create endpoints for managing user notifications"

Steps:

1. Create notificationRoutes.ts with routes:
   • GET /api/notifications - Get user's notifications
   • POST /api/notifications - Create new notification
   • PATCH /api/notifications/:id/read - Mark as read
   • DELETE /api/notifications/:id - Delete notification
2. Create notificationController.ts with all controller functions
3. Create notificationService.ts for database operations
4. Add authentication middleware to all routes
5. Register routes in index.ts