dynamic-api-builder-js

Configuration-driven REST API generator for Node.js — define your endpoints in JSON, get a fully working Express API instantly.

Table of Contents

• Overview
• Installation
• Quick Start
• Configuration
  • Database Config
  • API Config
• API Types
  • CRUD
  • TRANSACTION
  • CALL_FUNCTION
  • CALL_PROCEDURE
  • FUNCTION
• Hooks
• Validation
• Filters & Pagination
• Joins
• Response Format
• Advanced Usage
• API Reference

Overview

dynamic-api-builder-js (DAB) eliminates the boilerplate of writing Express routes, SQL queries, and request validation by hand. You declare your API endpoints as a JSON config, and DAB registers them on an Express router automatically — including CRUD operations, multi-step transactions, database function/procedure calls, and fully custom handlers.

Supports MySQL and PostgreSQL.

Installation

npm install dynamic-api-builder-js

Peer dependencies (install separately):

# For MySQL
npm install mysql2

# For PostgreSQL
npm install pg

Quick Start

const express = require('express');
const dabApi = require('dynamic-api-builder-js');

const app = express();
app.use(express.json());

const { router } = dabApi({
  database: {
    type: 'mysql',       // 'mysql' | 'postgres'
    host: 'localhost',
    port: 3306,
    user: 'root',
    password: 'secret',
    database: 'mydb',
  },
  apis: [
    {
      id: 'list-users',
      endpoint: '/users',
      method: 'GET',
      type: 'CRUD',
      operation: 'READ',
      table: 'users',
      columns: ['id', 'name', 'email'],
      pagination: true,
    },
    {
      id: 'create-user',
      endpoint: '/users',
      method: 'POST',
      type: 'CRUD',
      operation: 'CREATE',
      table: 'users',
      columns: ['name', 'email', 'password'],
    },
  ],
});

app.use('/api', router);
app.listen(3000, () => console.log('Server running on port 3000'));

Configuration

Database Config

Pass a database object at the top level of your config. DAB creates and manages the connection pool for you.

| Field | Type | Default | Description | |-------------------|----------|---------------|------------------------------------| | type | string | "mysql" | "mysql" or "postgres" | | host | string | "localhost" | Database host | | port | number | 3306 | Database port | | user | string | "root" | Database user | | password | string | "" | Database password | | database | string | "" | Database/schema name | | connectionLimit | number | 10 | Max connections in the pool |

API Config

Each entry in the apis array describes a single route.

| Field | Type | Required | Description | |--------------|----------|----------|----------------------------------------------------------| | id | string | No | Identifier used in logs and warnings | | endpoint | string | Yes | Express route path (e.g. /users/:id) | | method | string | Yes | HTTP method: GET, POST, PUT, DELETE, etc. | | type | string | Yes | API type (see API Types) | | validation | object | No | Validation rules (see Validation) | | hooks | object | No | before / after hook names (see Hooks) |

API Types

CRUD

Handles standard Create, Read, Update, Delete operations against a single table.

{
  id: 'get-user',
  endpoint: '/users/:id',
  method: 'GET',
  type: 'CRUD',
  operation: 'READ',       // 'CREATE' | 'READ' | 'UPDATE' | 'DELETE'
  table: 'users',
  columns: ['id', 'name', 'email'],
  filters: ['status', 'role'],        // query params used as WHERE filters
  pagination: true,                   // enables ?page=&limit= query params
  joins: [                            // optional JOIN clauses
    {
      type: 'LEFT',                   // 'INNER' | 'LEFT' | 'RIGHT'
      table: 'roles',
      condition: 'users.role_id = roles.id'
    }
  ],
  filterConfig: {
    name: { operator: 'LIKE' },       // override filter operator
    orFields: ['name', 'email']       // fields matched by ?_or= query param
  }
}

Operations:

| Operation | HTTP Method | Description | |------------|-------------|----------------------------------| | READ | GET | Fetch rows; supports filter/pagination | | CREATE | POST | Insert a new row | | UPDATE | PUT/PATCH | Update row by :id | | DELETE | DELETE | Delete row by :id |

TRANSACTION

Executes multiple database steps as an atomic transaction. Steps run in order; each step's result is passed to the next via map.

{
  id: 'transfer-funds',
  endpoint: '/transfer',
  method: 'POST',
  type: 'TRANSACTION',
  steps: [
    {
      operation: 'CREATE',
      table: 'ledger',
      columns: ['account_id', 'amount', 'type'],
    },
    {
      operation: 'UPDATE',
      table: 'balances',
      columns: ['balance'],
      map: {
        // Map a value from a previous step's result
        // "$stepResultKey.fieldName"
        balance: '$0.amount'
      }
    }
  ]
}

A step can also use a custom handler instead of a CRUD operation:

{ handler: 'myCustomHookName' }

CALL_FUNCTION

Calls a database scalar function and returns its result.

{
  id: 'get-discount',
  endpoint: '/discount',
  method: 'GET',
  type: 'CALL_FUNCTION',
  function: 'calculate_discount',     // DB function name
  params: [
    { name: 'user_id',   source: 'query'  },
    { name: 'coupon',    source: 'body'   },
    { name: 'currency',  source: 'static', value: 'INR' }
  ]
}

Parameter sources:

| Source | Reads from | |-----------|-------------------------------| | body | req.body[name] | | query | req.query[name] | | params | req.params[name] | | headers | req.headers[name] | | static | Hardcoded value in config |

CALL_PROCEDURE

Calls a stored procedure. Returns a single result set or an array of result sets when the procedure returns multiple.

{
  id: 'sync-inventory',
  endpoint: '/inventory/sync',
  method: 'POST',
  type: 'CALL_PROCEDURE',
  procedure: 'sync_inventory_proc',
  params: [
    { name: 'warehouse_id', source: 'body' },
    { name: 'triggered_by', source: 'static', value: 'api' }
  ]
}

FUNCTION

Executes a fully custom JavaScript handler — useful for complex logic that doesn't fit the other types.

const { hooks } = dabApi({ ... });

hooks.register('myHandler', async (req) => {
  // any custom logic
  return { message: 'done' };
});

// In your API config:
{
  id: 'custom-endpoint',
  endpoint: '/custom',
  method: 'POST',
  type: 'FUNCTION',
  handler: 'myHandler'
}

Hooks

Hooks let you run code before or after the main operation executes — great for password hashing, logging, or enriching response data.

const { hooks } = dabApi(config);

// Register a hook
hooks.register('hashPassword', async (req) => {
  if (req.body.password) {
    req.body.password = await bcrypt.hash(req.body.password, 10);
  }
});

// Use in API config
{
  type: 'CRUD',
  operation: 'CREATE',
  table: 'users',
  columns: ['name', 'email', 'password'],
  hooks: {
    before: 'hashPassword',   // runs before the DB operation
    after: 'sendWelcomeEmail' // runs after, receives (req, result)
  }
}

Built-in hooks (registered automatically):

| Hook Name | Description | |------------------|-------------------------------------------------| | hashPassword | Hashes req.body.password using bcrypt before saving |

Hook methods on DabHooks:

hooks.register('name', fn)           // register a single hook
hooks.registerBatch({ name: fn })    // register multiple at once
hooks.has('name')                    // check if a hook exists → boolean
hooks.remove('name')                 // unregister a hook

Validation

Add a validation object to any API config to enforce rules on request fields.

{
  type: 'CRUD',
  operation: 'CREATE',
  table: 'users',
  columns: ['name', 'email'],
  validation: {
    name:  { required: true, minLength: 2, maxLength: 100 },
    email: { required: true, type: 'email' },
    age:   { type: 'number', min: 18 },
  }
}

Validation failures return HTTP 400 with a structured error:

{
  "success": false,
  "error": {
    "message": "Validation failed",
    "code": 400,
    "details": [ ... ]
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Filters & Pagination

Filters

List field names in the filters array. DAB maps them from query parameters to SQL WHERE clauses automatically.

GET /users?status=active&role=admin

Use filterConfig to customize operators:

filterConfig: {
  name:     { operator: 'LIKE' },   // WHERE name LIKE '%value%'
  age:      { operator: '>=' },
  orFields: ['name', 'email']       // WHERE (name = ? OR email = ?)
}

Pass comma-separated values for an IN clause:

GET /users?role=admin,manager

Pagination

Enable with pagination: true. Control via query params:

GET /users?page=2&limit=20

Joins

joins: [
  {
    type: 'LEFT',    // 'INNER' | 'LEFT' | 'RIGHT'
    table: 'roles',
    condition: 'users.role_id = roles.id'
  }
]

Response Format

All responses follow a consistent structure.

Success:

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Error:

{
  "success": false,
  "error": {
    "message": "Duplicate entry",
    "code": 409,
    "details": null
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

DAB automatically maps common database error codes (duplicate entry, foreign key violation, null constraint, missing table) to appropriate HTTP status codes.

Advanced Usage

Attaching middleware

Pass a middleware option to dabApi() to run middleware before every registered route:

const { router } = dabApi(config, {
  middleware: [authMiddleware, rateLimitMiddleware]
});

Accessing sub-modules

dabApi() returns an object with all internal modules exposed:

const { router, validator, executor, queryBuilder, hooks, response } = dabApi(config);

Running raw queries

const { queryBuilder } = dabApi(config);

await queryBuilder.initPool();
const rows = await queryBuilder.execute('SELECT * FROM users WHERE id = ?', [1]);

Transactions

await queryBuilder.beginTransaction();
try {
  await queryBuilder.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, 1]);
  await queryBuilder.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, 2]);
  await queryBuilder.commitTransaction();
} catch (err) {
  await queryBuilder.rollbackTransaction();
  throw err;
}

API Reference

dabApi(config, options?)

Main entry point. Returns { router, validator, executor, queryBuilder, hooks, response }.

| Param | Type | Description | |--------------------|------------|------------------------------------------| | config.database | object | DB connection config (optional if pool already configured) | | config.apis | array | Array of API definitions (required) | | options.middleware | fn\|fn[] | Middleware to run before every route |

DabQueryBuilder

| Method | Description | |---------------------------------|------------------------------------------| | configure(config) | Set DB config and initialize pool | | initPool() | Open and verify the connection pool | | execute(sql, params) | Run a raw parameterized query | | beginTransaction() | Start a DB transaction | | commitTransaction() | Commit the active transaction | | rollbackTransaction() | Roll back the active transaction | | closePool() | Drain and close the pool |

DabHooks

| Method | Description | |-------------------------------|------------------------------------------| | register(name, fn) | Register a hook function | | registerBatch(obj) | Register multiple hooks | | execute(name, req, data?) | Execute a registered hook | | has(name) | Check if a hook is registered | | remove(name) | Unregister a hook |

Author

Gulshan Marandi

License

ISC