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. appKey header (legacy encrypted app identifier)
3. 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/:domain

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

Localhost example

curl -X POST http://localhost:3001/getApp/localhost \
	-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/localhost`, {
		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