hana-developer-cli-tool-example route-development.instructions.md

Route Development Guidelines

Use this guide when creating or modifying route files in the routes/ directory.

Scope and Purpose

This guide applies to all route files in routes/. Each file exports a route(app, server) function that registers one or more related endpoints on the Express application. Routes serve as bridges between HTTP clients and CLI commands.

Critical Principles

1. Consistency: All routes follow the same structural pattern and registration method.
2. Error Handling: Errors propagate to centralized Express error middleware, never handled inline.
3. Connection Management: Database connections are cleared before use and created as needed.
4. Internationalization: All user-facing strings come from i18n bundles via base.bundle.getText(key).
5. Response Standardization: Use base.sendResults(res, results) for consistent JSON response formatting.
6. Swagger Documentation: Every endpoint includes JSDoc comments for auto-generated API docs.
7. CLI Integration: Dynamic imports enable newly added CLI commands to be instantly available to routes.
8. Dual Support: When applicable, support both API (/path) and UI (/path-ui) endpoint variants.

File Structure Template

Every route file must follow this structure:

/**
 * @fileoverview [Brief description of what these routes handle]
 * 
 * Routes:
 *  - GET /path1 - [Description]
 *  - GET /path2 - [Description]
 * 
 * Dependencies: CLI commands at bin/[commandName].js, utils/base.js
 */

export async function route(app, server) {
  const base = await import('../utils/base.js')
  
  /**
   * @swagger
   * /path1:
   *   get:
   *     tags:
   *       - Category Name
   *     summary: Brief endpoint description
   *     description: Detailed endpoint description from i18n
   *     responses:
   *       200:
   *         description: Success response
   */
  app.get('/path1', async (req, res, next) => {
    try {
      // Endpoint logic
      res.status(200).json(result)
    } catch (error) {
      next(error)
    }
  })
}