The API

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ES Module context, which is the default for `the-api`.
  fix Ensure your project is configured for ES Modules by adding `"type": "module"` to your `package.json`. Change `require()` statements to `import` statements.

• error: database "your_database_name" does not exist

  cause The PostgreSQL database specified in your environment variables (e.g., `DB_DATABASE`) has not been created.
  fix Manually create the database on your PostgreSQL server using `createdb your_database_name` or a GUI tool.

• Error: Missing environment variable: DB_HOST

  cause A required environment variable (e.g., `DB_HOST`, `DB_USER`) for database connection or other configurations is not set, or your `.env` file is not being loaded.
  fix Check your `.env` file for missing variables and ensure it's loaded correctly, e.g., by running your Node.js application with `node --env-file=.env index.js`.

Warnings

• breaking The-api package is designed for ES Modules (ESM) environments. If using Node.js, ensure your `package.json` includes `"type": "module"`.
  Fix: Add `"type": "module"` to your `package.json` file. Update `require()` calls to `import` statements if migrating from CommonJS.
• gotcha When using environment variables (e.g., for database connection) with Node.js, you must explicitly load them, for example, by running `node --env-file=.env index.js`. Unlike some other runtimes, Node.js does not automatically load `.env` files.
  Fix: Use `node --env-file=.env your-app.js` or integrate a package like `dotenv` for programmatic loading if the `--env-file` flag is not suitable.
• gotcha The automatic CRUD features and database migrations provided by the-api rely on `knex`. You must install `knex` and the appropriate database client (e.g., `pg` for PostgreSQL) separately, and configure your database connection.
  Fix: Install `knex` and your database client: `npm install knex pg`. Configure database connection details in your `.env` file or directly in the `TheAPI` constructor options.

Install

• npm install the-api npm
• yarn add the-api yarn
• pnpm add the-api pnpm

Imports

• TheAPI
  wrong:

  const { TheAPI } = require('the-api');

  correct:

  import { TheAPI } from 'the-api';

  The-api is designed for ESM. CommonJS 'require' will not work directly.
• Routings
  wrong:

  import Routings from 'the-api';

  correct:

  import { Routings } from 'the-api';

  Routings is a named export for defining route groups and individual routes.
• middlewares
  wrong:

  import * as middlewares from 'the-api/middlewares';

  correct:

  import { middlewares } from 'the-api';

  Built-in middlewares are exposed as a named export from the main package.

Quickstart

This quickstart demonstrates how to set up a basic The API server with a GET route using path parameters.

import { Routings, TheAPI, middlewares } from 'the-api';

const router = new Routings();

// Define a GET route with a path parameter
router.get('/data/:id', async (c) => {
  const { id } = c.req.param();        // Extract route parameter 'id'
  // Simulate an async operation, e.g., fetching from a DB
  await new Promise(resolve => setTimeout(resolve, 50));
  c.set('result', { id, foo: 'bar', timestamp: new Date().toISOString() }); // Set response result
});

// Initialize TheAPI with common middlewares and our defined router
const theAPI = new TheAPI({ routings: [middlewares.common, router] });

// Start the server (using top-level await)
try {
  await theAPI.up(); // For Node.js
  console.log('TheAPI server started on http://localhost:7788');
  // For Bun, you would typically export the result of theAPI.upBun();
  // export default await theAPI.upBun();
} catch (error) {
  console.error('Failed to start TheAPI server:', error);
  process.exit(1);
}