Creating Routes

Learn how to define and organize routes in Asimilation

Routes are the foundation of your Asimilation application. This guide will walk you through creating routes, defining HTTP methods, and organizing your route definitions.

Basic Route Creation

Use the addPath() method to create a route. Routes are added to the url manager exported from Asimilation:

import { url } from '@asimilation/core';
import { ArgumentedIncomingMessageAbc, ArgumentedServerResponseAbc } from '@asimilation/core';

url.addPath('/hello', (req: ArgumentedIncomingMessageAbc, res: ArgumentedServerResponseAbc) => {
  res.sendJson({ message: 'Hello, World!' }, 200);
});

By default, routes respond to all HTTP methods unless you specify otherwise using the methods option.

Specifying HTTP Methods

Control which HTTP methods a route responds to using the methods option in the third parameter:

url.addPath('/users', (req, res) => {
  res.sendJson({ users: [] }, 200);
}, {
  methods: ['GET']
});

url.addPath('/users', (req, res) => {
  res.sendJson({ message: 'User created' }, 201);
}, {
  methods: ['POST']
});

You can register the same path with different HTTP methods by calling addPath() multiple times with different methods options.

Multiple Methods on One Route

Handle multiple HTTP methods with a single route definition:

url.addPath('/api/data', (req, res) => {
  if (req.method === 'GET') {
    res.sendJson({ data: 'fetched' }, 200);
  } else if (req.method === 'POST') {
    res.sendJson({ data: 'created' }, 201);
  }
}, {
  methods: ['GET', 'POST']
});

Response Helpers

Asimilation provides convenient response methods on the enhanced response object:

JSON Response

res.sendJson({ message: 'Success' }, 200);

Path Normalization

Asimilation automatically normalizes paths for you:

// These are all equivalent:
url.addPath('/api/users', handler);
url.addPath('api/users', handler);    // Leading slash added
url.addPath('/api//users', handler);  // Multiple slashes normalized

Path normalization is handled by the normalizePath() function (see src/helpers/url-regex.ts:38-47).

Organizing Routes with Modules

For larger applications, organize routes using RouteModule. This allows you to create namespaced route groups:

import { url } from '@asimilation/core';

// Create a module with a base path
const apiModule = url.createRouteModule('/api');

// All routes in this module are prefixed with /api
apiModule.addPath('/users', (req, res) => {
  res.sendJson({ users: [] }, 200);
}); // Responds to /api/users

apiModule.addPath('/posts', (req, res) => {
  res.sendJson({ posts: [] }, 200);
}); // Responds to /api/posts

Nested Route Modules

Create nested modules for deeper organization:

const apiModule = url.createRouteModule('/api');
const v1Module = apiModule.createRouteModule('/v1');

// This route responds to /api/v1/users
v1Module.addPath('/users', (req, res) => {
  res.sendJson({ version: 'v1', users: [] }, 200);
});

Route modules automatically handle path concatenation and normalization (see src/core/router-manager.ts:148-172).

Organizing Routes in Separate Files

For better code organization, split routes into separate files:

routes/users.ts

import { RouteManagerI } from '@asimilation/core';

export function registerUserRoutes(router: RouteManagerI) {
  router.addPath('/users', (req, res) => {
    res.sendJson({ users: [] }, 200);
  }, { methods: ['GET'] });

  router.addPath('/users', (req, res) => {
    res.sendJson({ message: 'User created' }, 201);
  }, { methods: ['POST'] });
}

Best Practices

1. Use descriptive paths

   Make your route paths clear and RESTful:

   • /users - Collection
   • /users/<int:id> - Specific resource
   • /users/<int:id>/posts - Nested resource
2. Organize by feature

   Group related routes in modules or separate files:

   const authModule = url.createRouteModule('/auth');
   const apiModule = url.createRouteModule('/api');
   
3. Specify HTTP methods

   Always specify which HTTP methods a route should handle:

   url.addPath('/resource', handler, { methods: ['GET', 'POST'] });
   
4. Use consistent status codes

   • 200 - Success (GET)
   • 201 - Created (POST)
   • 204 - No Content (DELETE)
   • 404 - Not Found
   • 500 - Server Error

What’s Next?

Dynamic Routes

Learn how to handle URL parameters and dynamic paths

Middleware

Add middleware to your routes for authentication, logging, and more