Managing API Endpoints with Kraken.js Convention-Based Routing

The Problem: Route Bloat and Manual Registration

In traditional Express.js applications, as the number of endpoints grows, the main application file often becomes a bottleneck of manual app.use() and app.get() declarations. This leads to merge conflicts in version control and makes it difficult for new developers to locate the logic associated with a specific URL path.

The takeaway: Kraken.js solves this by using convention-over-configuration. Instead of manually registering routes in a central file, Kraken.js automatically maps the directory structure within the services/ folder to your API endpoints. Adding a new feature is as simple as creating a new directory and exporting a configuration function.

How Service-Based Routing Works

Kraken.js treats every folder under the services/ directory as a modular unit. Each service is expected to export a function that receives the Express application instance. This decoupling allows you to isolate business logic and middleware for specific domains without touching the core server configuration.

Worked Example: Implementing a User Service

To create a /users endpoint, you do not edit the main server file. Instead, you follow this structure:

# Directory structure
project-root/
└── services/
    └── users/
        └── index.js

In services/users/index.js, export a function that defines your routes. You must use the app instance passed by the framework to register your endpoints:

// services/users/index.js
module.exports = function (app) {
    // Define a route specific to the user service
    app.get('/users', (req, res) => {
        res.json({
            message: 'User list retrieved successfully',
            data: []
        });
    });

    // Example of a parameterized route
    app.get('/users/:id', (req, res) => {
        const userId = req.params.id;
        res.json({ userId, status: 'active' });
    });
};

Execution and Permissions: Run the application using the standard npm start command from the project root. Ensure the user running the process has read permissions for the services/ directory. Kraken.js will scan the folder at startup and execute the exported function, effectively registering /users and /users/:id into the Express routing table.

Integrating Service-Level Middleware

Because Kraken.js provides the Express app instance directly to the service, you can apply middleware to specific routes within that service. This is useful for implementing domain-specific validation or authentication that shouldn't run on every global request.

module.exports = function (app) {
    const validateUserRequest = (req, res, next) => {
        if (!req.query.apiKey) {
            return res.status(401).send('API Key Required');
        }
        next();
    };

    // Apply middleware only to this specific route
    app.get('/users/secure-data', validateUserRequest, (req, res) => {
        res.send('Sensitive user data');
    });
};

Limitations and Common Pitfalls

Naming and Export Failures

The automatic registration relies entirely on the export pattern. If you use exports.init = function... instead of module.exports = function..., Kraken.js will not find the entry point, and the routes will simply not exist. There is often no explicit error thrown; the routes will return a 404 Not Found.

Tracing Request Flow

As the project grows, the lack of a central route file can make it difficult to trace a request. To verify which routes are active, you should check the application logs during the bootstrap phase or use a diagnostic tool to list registered Express routes.

Middleware Conflicts

Since Kraken.js is built on Express, global middleware defined in the framework's core configuration runs before service-level middleware. Avoid redefining global headers or body-parsers inside individual services, as this can lead to unexpected behavior or double-processing of request bodies.

Verification and Testing

To confirm your service is correctly registered, perform the following checks:

• Endpoint Reachability: Use curl -I http://localhost:PORT/users. A 200 OK indicates the service was discovered and the function executed.
• Middleware Order: Create a test route with a custom logger middleware. Verify that the global Kraken.js logs appear before your service-specific logs in the console.
• Isolation Test: Rename the services/users folder to services/user_backup. Restart the server and verify that /users now returns a 404, confirming that the routing is indeed driven by the directory name and presence.