Data Exposition (Exposed Entities)

By default, none of the tables (entities) in your Data Domain are accessible over the web. You must explicitly expose them as Exposed Entities in the API Modeler to generate REST API endpoints.

When exposing an entity, you configure two main types of endpoints: Collections and Resources.

---

Collections vs. Resources

To design clean APIs, it is important to understand the distinction between collections and single resources:

1. The Collection

A Collection represents a group or list of multiple records.

• Analogy: A folder containing many files.
• URL Path: Typically a plural noun starting with a forward slash (e.g., /posts, /products, /orders).
• Actions: Associated with list-level or creation operations, such as List (fetch all), Search (find matching items), or Create (add a new record to the collection).

2. The Resource

A Resource represents one single, specific record within the system.

• Analogy: A single file inside a folder.
• URL Path: Composed of the collection path followed by a unique identifier parameter segment (e.g., /posts/{postId} or /products/{id}).
• Actions: Associated with operations on a specific item, such as Read (view one), Update (edit one), or Delete (remove one).

---

Endpoint Configuration Rules

In the API Modeler UI, you define these paths using two main fields:

Collection Path

The URL path representing the list of records (e.g., /posts).

• Rules: Must be a single path segment starting with a forward slash (e.g., /posts). It cannot contain sub-paths (like /posts/active) or parameters.

Resource Path

The URL path representing a single record (e.g., /posts/{postId}).

• Rules:
  • If the entity has a collection exposed, the resource path must start with the collection path, followed by a unique identifier parameter in curly braces (e.g., /posts/{postId}).
  • If the entity represents a single item (no collection exposed, like a user’s single /profile), the resource path must consist of exactly two segments including the parameter (e.g., /profile/{id}).

---

Routing Validation & Path Collisions

To ensure your API operates correctly and does not experience routing conflicts, the platform’s validator automatically enforces the following checks:

• No Path Collisions: No two exposed entities share the same Collection Path or Resource Path.
• Parameter Sync: The identifier parameter name in the Resource Path (e.g., {postId}) matches the entity’s primary key property.
• Unique Parameter Names: All path parameter names within a single URL path must be unique. For example, you cannot configure a nested path like /users/{id}/posts/{id} because the runtime will not be able to distinguish between the user ID and the post ID. Instead, use distinct names like /users/{userId}/posts/{postId}.

---

Entity Configuration Tabs

When configuring an exposed entity in the API Modeler UI, you are presented with a configuration panel organized into four distinct tabs. These tabs allow you to customize routing, supported actions, query capabilities, authorization rules, and rate limits for that specific entity.

1. Endpoint Tab

The Endpoint tab is where you configure the core HTTP routing and allowed operations.

• Endpoint Section: Define the Collection Path (e.g., /posts) and Resource Path (e.g., /posts/{postId}) according to the path validation rules.
• Actions Section: Toggle which CRUD and Query actions are enabled for this entity. At least one action must be selected to avoid configuration warnings. The available actions are:
  • Create: Allows inserting new records (POST /{collectionPath}).
  • List: Allows retrieving a paginated list of records (GET /{collectionPath}).
  • Search: Allows querying records using an AST-based filter body (POST /{collectionPath}/search).
  • Read: Allows retrieving a single record by its primary key (GET /{collectionPath}/{resourcePath}).
  • Update: Allows modifying existing records (PUT or PATCH on /{collectionPath}/{resourcePath}).
  • Delete: Allows removing records (DELETE /{collectionPath}/{resourcePath}).

2. Indexes Tab

The Indexes tab defines how clients can query, filter, sort, and search the entity’s records.

• Only fields that have been marked with index or search in the Data Modeler UI are available here.
• For each indexed field, you can separately enable or disable its inclusion in:
  • Sorting: Whether clients can sort results by this field (e.g., sort=-created_at).
  • Filtering: Whether clients can filter results using comparison operators on this field (e.g., status[eq]=active).
  • Search: Whether clients can perform keyword or substring searches against this field.

3. Access Tab

The Access tab controls endpoint-level authorization.

• By default, the endpoints for this entity inherit the access rules defined globally on the API.
• You can override the inherited rules on a per-action basis (matching the action names: Create, List, Search, Read, Update, Delete).
• This allows you to specify custom roles or access permissions for specific endpoints (for example, allowing anyone to Read posts but restricting Create and Update to administrators).

4. Limits Tab

The Limits tab governs rate limiting configurations to protect your API from abuse.

• By default, rate limits are inherited from the global API configuration.
• You can override the rate limiting configuration specifically for this entity to set custom thresholds (e.g., allowing fewer requests per minute on resource-intensive endpoints like Search or Update).