Skip to content
API Now LogoAPI Now LogoDocumentation
API Now! is currently in closed beta. We are constantly updating these guides as we release updates!

Data Entities

A Data Entity (DomainEntity) represents a physical table in your generated database and the primary blueprint for a business concept (e.g. User, Product, Order).

Inside the Domain Modeler, entities are the main building blocks where you define columns (properties) and relationships (associations).

Setting Up an Entity

Section titled “Setting Up an Entity”

When you add a new entity to a Data Model, you configure the following primary properties:

  • Name: The physical database table name. This must be a valid database identifier (typically lowercase alphanumeric characters and underscores, like customer_profile).
  • Display Name (Optional): A human-friendly name (e.g., Customer Profile) that replaces the raw entity name in the UI for presentation purposes.
  • Description (Recommended): A clear summary of the entity’s purpose to document your schema.

Key and Primary Properties

Section titled “Key and Primary Properties”

API Now! does not automatically provision an implicit primary key field. Instead, every entity must have at least one property designated as the primary key. This is configured on the property level by checking the Primary attribute checkbox on a property (e.g., a custom id field).

Primary keys are always immutable on update (PUT / PATCH). On creation (POST), primary keys follow one of two patterns:

  • Server-Generated Primary Key (primary: true, readOnly: true): The database sequence or server generator populates the unique identifier (e.g., PostgreSQL SERIAL, BIGINT IDENTITY, auto-generated UUIDv4). API clients cannot supply an ID on creation. This is the default setting when toggling Primary Key ON.
  • Client-Assignable Primary Key (Natural Key) (primary: true, immutable: true): Callers supply their own natural identifier when creating records (e.g., project key: "PROJ", ISO currency code USD, SKU, or client-generated UUIDv7). Once created, the identifier is permanently locked against changes.

For full architectural details and OpenAPI schema generation contracts, see Primary Key Patterns.

Entity Inheritance

Section titled “Entity Inheritance”

API Now! supports Entity Inheritance, allowing one entity to extend the structure and properties of another parent entity.

graph TD
    User[User Entity]
    Employee[Employee Entity] -->|Inherits| User
    Customer[Customer Entity] -->|Inherits| User

How it Works

Section titled “How it Works”
  • Property Inheritance: The child entity automatically inherits all properties defined on the parent entity. For example, if User has email and password, Employee will automatically receive those properties without duplicating them.
  • Multiple Parents: An entity can inherit properties from multiple parent entities.
  • Resolution (Shadowing / Last Property Wins): When property names clash, the child property (or the last parent) wins. A child entity can shadow (override) an inherited property by defining a property with the exact same name.
  • Physical Schema (Flattened Tables): In the physical database, the platform does not create parent-child table structures or perform runtime joins. Instead, all tables are completely flattened at deploy time, meaning the child table physically contains all of its own properties along with all inherited parent properties.
  • Lifecycle Status Constraint: An entity can have at most one property annotated with the Status semantic module across its full inheritance hierarchy. If a parent defines a status property, a child entity cannot introduce a second, differently named status field, nor can it inherit conflicting status properties from multiple parents. However, a child entity can shadow (override) the parent’s status property by declaring a property with the same name to customize the lifecycle states or transition rules specifically for that child entity.

Standard System Entities

Section titled “Standard System Entities”

When creating a new Data Domain, it is common to designate certain entities with standard system meanings:

  • The User Entity: Applying the User semantic module to an entity designates it as the primary table for system logins and access control.