Getting Started

Introduction

The Infomaxim API provides a comprehensive backend-as-a-service platform for building web and mobile applications. Our API offers:

• RESTful architecture with JSON responses
• JWT-based authentication and authorization
• Flexible data management with secure querying
• File storage and management
• E-commerce capabilities with Stripe integration
• Real-time analytics and reporting
• Email and push notification services

Installation & Configuration

Prerequisites

• Node.js 14.x or higher
• Microsoft SQL Server
• IIS (Internet Information Services) for production deployment

Environment Setup

Clone the repository and install dependencies:

git clone https://github.com/andy008/Infomaxim.git
cd Infomaxim/projects/api
npm install

Configuration File

Create a .env file in the API root directory with the following variables:

# Database Configuration
DB_NAME=infomaxim
DB_SERVER=your-server-name
DB_USER=your-username
DB_PASSWORD=your-password
DB_ENCRYPT=true

# JWT Secrets
JWT_ACCESS_SECRET=your-access-token-secret
JWT_REFRESH_SECRET=your-refresh-token-secret
JWT_ACCESS_TOKEN_LIFE=3600
JWT_REFRESH_TOKEN_LIFE=2592000

# API Configuration
API_PORT=3001
FRONTEND_DOMAIN=http://localhost:4200

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# Encryption
ENCRYPTION_KEY=your-32-byte-encryption-key
ENCRYPTION_IV=your-16-byte-initialization-vector

Database Setup

The API connects to an existing Infomaxim database. Ensure your database is properly configured with:

• User authentication tables
• Application configuration tables
• Dynamic data tables based on your schema

Starting the API Server

For development:

npm start

For production:

npm run start-prod

App Identification & Initialization

Infomaxim is multi-tenant, so each request runs in an application context (appID). Your website will be set up to identify your app automatically in production.

Your appID

You will be given a numeric appID for your application (for example, 42). Use this appID in development when calling public endpoints from localhost.

How app identification works

1. site-id header (recommended and explicit)
2. Request host/domain resolution

In non-production localhost workflows, appID in the request body can be used as a development fallback for both authenticated and unauthenticated requests. This is intended for local development. In production, use normal app resolution (site-id and/or host-based resolution).

Initialize your frontend with POST /getApp

Call /getApp when your app boots to load tenant branding and client configuration (for example logo, theme colors, and Stripe publishable key).

The API resolves domain context from request host headers (for example host/x-forwarded-host), with site-id as the recommended explicit override.

Localhost example

curl -X POST http://localhost:3001/getApp \
	-H "site-id: 42"

JavaScript example

const APP_ID = 42; // Your assigned Infomaxim appID
const API_BASE = 'http://localhost:3001';

async function initApp() {
	const response = await fetch(`${API_BASE}/getApp`, {
		method: 'POST',
		headers: {
			'site-id': String(APP_ID)
		}
	});

	if (!response.ok) {
		throw new Error('Failed to initialize app configuration');
	}

	const config = await response.json();
	return config;
}

Typical response data

{
	"splash_logo": "/files/splash-logo.png",
	"logo": "/files/logo.png",
	"background": "#ffffff",
	"colour1": "#111111",
	"colour2": "#222222",
	"stripe_live_public_key": "pk_live_xxx",
	"_id": "encrypted-app-id",
	"_publicKey": "AABBCC"
}

If you cannot send site-id in a browser call during local development (for example due to CORS restrictions), use a local backend proxy so the header is added server-side.

IIS Configuration

URL Rewrite Rule

Configure IIS to proxy requests to the Node.js API server. Add the following rule to your web.config:

<rewrite>
  <rules>
    <rule name="V2 Infomaxim API" enabled="true" patternSyntax="ECMAScript" stopProcessing="true">
      <match url="infomaxim/api/v2/(.*)" />
      <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
      <action type="Rewrite" url="http://localhost:3001/{R:1}" />
      <serverVariables>
        <set name="HTTP_site-id" value="1" />
      </serverVariables>
    </rule>
  </rules>
</rewrite>

Alternatively, you can set the application ID in the config settings for the node application

    
  app: {
    id: 10 // Application ID for this instance
  }
  

Determining Application ID

The config setting takes precedence, then the HTTP_site-id server variable, and finally the x-original-host header.

Server Variables Configuration

1. Open IIS Manager
2. Select your website
3. Open "URL Rewrite"
4. Click "View Server Variables" in the Actions panel
5. Add HTTP_site-id to the allowed server variables list

Domain Configuration

The API uses the HTTP_site-id server variable to determine which Infomaxim application database to connect to. Each IIS website can have a different site-id, allowing multiple applications to run on the same API server.

Base URL & Endpoints

API Base URLs

Standard Response Format

All API endpoints return JSON responses in the following format:

Success Response

{
  "status": "Success",
  "data": { 
    /* Response data */
  },
  "datetime": "2024-01-01T12:00:00Z"
}

Error Response

{
  "status": "Failed",
  "message": "Error description",
  "errors": [
    {
      "field": "fieldName",
      "message": "Field-specific error message"
    }
  ]
}

HTTP Status Codes

Encrypted API Properties

Some API properties are intentionally encrypted when returned to clients. These values are safe for transport and should be passed back to the API as-is in the matching request property.

How to identify encrypted values

• Fields that start with an underscore often represent encrypted identifiers (for example, _id).
• Legacy encrypted token format may also appear in some payloads as _[iv:ciphertext].

Return and pass-back pattern

When you receive an encrypted identifier, pass it back using the same API contract. Do not decrypt it in frontend code.

// response row example
{
	"title": "My record",
	"_id": "75ae847bb70c07995712ad659ffd4bca:8b43a60f2d0597c83fa4ace3e81bb563"
}

// request example (send encrypted value back)
{
	"table": "aurora_products",
	"_id": "75ae847bb70c07995712ad659ffd4bca:8b43a60f2d0597c83fa4ace3e81bb563"
}

Important notes

• Do not parse, trim, or transform encrypted strings before sending them back.
• For secure filtering, prefer whereConditions and pass raw IDs where possible.
• If a request value is encrypted, the API will normalize/decrypt supported encrypted token formats before building SQL parameters.