Single Database Architecture & Multi-API Integration

In API Now!, every organization is provisioned with a single, unified PostgreSQL database that powers all of the organization’s deployed APIs.

This single-database architecture eliminates the operational overhead of managing multiple database servers. However, it introduces two important architectural considerations:

1. How do we prevent accidental table name collisions when different APIs define tables with identical names (such as User or Settings)?
2. How do we share a single, unified User table across multiple APIs (for example, a public customer API and an internal admin API)?

---

1. Single Database per Organization: How It Works

When you deploy any API in API Now!, the Serverless Runtime connects directly to your organization’s dedicated database and automatically manages the physical tables, indexes, and constraints.

flowchart TD
    subgraph OrgDB["Organization Dedicated PostgreSQL Database"]
        direction TB
        subgraph Isolated["Pattern 1: Isolated APIs (Default)"]
            T1["Storefront User Table<br/><code>a1b2c3d4_user</code>"]
            T2["Admin User Table<br/><code>z9y8x7w6_user</code>"]
        end
        subgraph Integrated["Pattern 2: Integrated APIs (Shared Domain)"]
            SharedUser["Unified User Table<br/><code>auth8899_user</code>"]
            Orders["Storefront Orders<br/><code>ecom1122_order</code>"]
            AdminLogs["Admin Audit Logs<br/><code>admn3344_audit_log</code>"]
            Orders -->|Foreign Key| SharedUser
            AdminLogs -->|Foreign Key| SharedUser
        end
    end

---

2. Default Safety: Automatic Table Name Prefixing

To guarantee that deployments never fail or overwrite each other when different APIs declare tables with the same name, API Now! uses automatic table name prefixing.

The Data Domain Key (NanoID)

• Every Data Domain you create receives an auto-generated, unique NanoID key (such as k9s8f7d6a5b4c3e2).
• When generating physical PostgreSQL tables, the runtime extracts the first 8 characters of the Data Domain key and prepends it to each entity’s table name.

Data Domain	Domain Key	Entity Name	Generated PostgreSQL Table Name
Customer Storefront	a1b2c3d4e5f6g7h8	User	a1b2c3d4_user
Internal Admin Portal	z9y8x7w6v5u4t3s2	User	z9y8x7w6_user

Because of this prefixing, both APIs can safely declare a User entity without table collisions, data corruption, or deployment failures.

---

3. The Integrated APIs Pattern: Sharing a Unified User Entity

While independent table prefixes are ideal for isolated projects, many organizations want integrated APIs that operate on the exact same user base.

A classic example is:

• Public Customer API (/api/v1): Customers register, log in, browse products, and place orders.
• Internal Admin API (/admin/v1): Editors and support staff manage user accounts, review orders, and ban malicious users.

If both APIs create their own local User entity, they will point to two separate tables (a1b2c3d4_user and z9y8x7w6_user), and an admin would not see customer accounts!

The Solution: The Shared Identity Domain Workflow

To have multiple APIs share the same physical database table, follow this 4-step workflow:

flowchart LR
    A["<b>1. Auth Domain</b><br/>Create Domain with User entity"] 
    --> B["<b>2. Publish to Catalog</b><br/>Publish with Organization Scope"] 
    --> C["<b>3. Foreign Domain Import</b><br/>Import into Storefront & Admin domains"] 
    --> D["<b>4. Deploy APIs</b><br/>Both point to <code>auth_user</code> table"]

Step 1: Create a Dedicated Identity Domain

1. In the Data Modeler, create a new Data Domain named auth (or identity-core).
2. Add the User entity and configure its properties:
   • email (annotated with Email and Username semantics)
   • password (annotated with Password semantic)
   • role (annotated with UserRole semantic)
   • Optional: profile_picture, phone, first_name, last_name

Step 2: Publish the Domain to the Data Catalog

1. In the top navigation bar, click Publish to Catalog.
2. Set the version tag (e.g. 1.0.0).
3. Set the Publishing Scope to Organization (so all projects in your organization can access it).
4. Click Publish.

Step 3: Import the Identity Domain into Your APIs

1. Open your Storefront Data Domain. In the domain settings, click Import Foreign Domain and select auth (v1.0.0).
2. Connect your local entities (e.g. Order) to the imported User entity via associations (e.g. Order.customer -> User).
3. Open your Admin Data Domain and also import auth (v1.0.0).

Step 4: Deploy Your Integrated APIs

When a Data Domain imports a foreign domain, the runtime preserves the foreign domain’s original prefix for all imported entities:

• Order entity (local to Storefront) $\rightarrow$ compiled to ecom_order
• AuditLog entity (local to Admin) $\rightarrow$ compiled to admn_audit_log
• User entity (imported from auth) $\rightarrow$ compiled to auth_user in both APIs!

Now, when a customer registers via the Customer API, their account is instantly visible and manageable by support staff in the Admin API.

---

4. Creating Local Isolated Alternatives

If an API within your organization genuinely requires an isolated, private user table (such as a separate SupportAgent or KioskUser table that should never mix with regular customers), you can simply define a local entity directly in that API’s domain instead of importing from the catalog.

The local entity will automatically receive its own domain key prefix, ensuring complete physical separation in the PostgreSQL database.

---

Summary: Integration vs. Isolation

Requirement	Recommended Approach	Database Outcome
Unified Users & Single Sign-On	Publish auth domain to Catalog $\rightarrow$ Import into all API domains	All APIs read and write to the same auth_user table.
Independent / Unrelated APIs	Define local User entities in each domain	Separate tables (domA_user, domB_user) created automatically.
Shared Resource Catalog (e.g. Products)	Publish catalog domain $\rightarrow$ Import into Storefront & Inventory APIs	Both APIs share the catalog_product table.

---

Next Steps

• Data Catalog Guide: Learn how versioning and publishing scopes work.
• Quick Start Guide: Build and test your first API model in 5 minutes.
• Session Configuration: Configure JWT and Cookie session tokens across your APIs.