Data Actions

Once an entity is exposed, you configure which operations are permitted on it by adding Actions to the entity. Each action generates a specific endpoint and HTTP method.

An exposed entity must have at least one action configured, or it will generate a model warning.

---

CRUD Actions & Endpoint Types

The API Modeler supports the following standard actions:

Create (POST)

Exposes the endpoint to insert new records into the database.

• Request Method: POST /{collectionPath}
• Validations: Automatically runs schema validations against required properties and format checks on write.

Read (GET)

Retrieves a single record from the database by its primary key/ID.

• Request Method: GET /{collectionPath}/{resourcePath} (e.g. GET /posts/{postId})

Update (PUT/PATCH)

Edits an existing record.

• Request Method: You must select at least one allowed HTTP method:
  • PATCH: Used for partial updates (updating only a subset of fields provided in the request payload). For properties with a JSON data type, API Now! implements RFC 7396 JSON Merge Patch semantics. This allows clients to recursively merge updates into nested JSON structures or delete properties by sending null values (see JSON Merge Patch).
  • PUT: Used for complete replacements of the record payload.

Differences Between PUT and PATCH

When exposing an update action, it’s important to understand how PUT and PATCH differ, especially when handling optional fields and JSON data types:

Behavior	PATCH (Partial Update)	PUT (Full Replacement)
Omitted Fields	Kept intact as they currently exist in the database.	Cleared (set to null or their default values).
JSON Columns	JSON Merge Patch (RFC 7396): Recursively merges sub-keys.	Complete Overwrite: Overwrites the entire JSON object.

Illustration Example

Assume a User record exists in the database with the following values:

{
  "id": 1,
  "name": "Alex",
  "email": "alex@example.com",
  "config": {
    "theme": "dark",
    "fontSize": 14
  }
}

If a client sends this payload:

{
  "name": "Alexander",
  "config": {
    "theme": "light"
  }
}

Depending on the HTTP method used, the updated database record will be:

• Using PATCH:

  {
    "id": 1,
    "name": "Alexander",
    "email": "alex@example.com",
    "config": {
      "theme": "light",
      "fontSize": 14
    }
  }

  (Note that email remains unchanged, and config.fontSize is preserved due to recursive merge.)

• Using PUT:

  {
    "id": 1,
    "name": "Alexander",
    "email": null,
    "config": {
      "theme": "light"
    }
  }

  (Note that email is cleared, and config.fontSize is deleted because the JSON object was fully replaced.)

Delete (DELETE)

Removes a record from the database.

• Request Method: DELETE /{collectionPath}/{resourcePath}
• Deletion Strategy: You must select a deletion strategy:
  • soft (Soft Delete): Marks the record as deleted (hiding it from list and read actions) without physically deleting it from the database. Requires a DeletedFlag or DeletedTimestamp semantic to be set.
  • hard (Hard Delete): Physically deletes the data from the database.

---

Many-to-Many (M:N) Association Actions

To simplify managing Many-to-Many (M:N) relationships without exposing confusing “join table” entities to API consumers, the API Modeler allows authors to configure Sub-Resource API Actions directly on M:N association edges.

When an association is tagged with an M:N semantic (such as OrganizationMembers), the API Modeler UI lists the association as a configurable Sub-Resource under the parent entity.

Configurable Association Edge Actions

Authors can toggle which API actions are permitted on the M:N sub-resource:

• List (GET): Can consumers list associated records?
• Create / Link (POST): Can consumers add a link between records?
• Read (GET): Can consumers view a specific member’s association edge?
• Update (PATCH): Can consumers modify edge properties (e.g. changing roles)?
• Delete / Unlink (DELETE): Can consumers remove a relationship link?

Runtime Execution & Embedded Edge Properties

The API Now Runtime generates predictable sub-resource endpoints where pivot table edge properties are automatically embedded into request and response payloads.

Using OrganizationMembers (association named users on Organization) as an example:

1. List (GET /{parentPath}/{parentId}/{subResourcePath})

Returns an array of target entity objects, embedding pivot table edge properties inside each item:

• Request: GET /organizations/org_999/users
• Response: [{ "id": "user123", "name": "John", "role": "admin" }]

2. Create / Link (POST /{parentPath}/{parentId}/{subResourcePath})

Links a target entity to the parent by adding a record to the pivot table:

• Request: POST /organizations/org_999/users
• Payload: { "id": "user123", "role": "admin" } (Note: id references the primary key of the target entity)

3. Read (GET /{parentPath}/{parentId}/{subResourcePath}/{targetId})

Retrieves a specific target object along with its edge properties for this parent.

4. Update (PATCH /{parentPath}/{parentId}/{subResourcePath}/{targetId})

Modifies properties stored directly on the pivot table edge:

• Request: PATCH /organizations/org_999/users/user123
• Payload: { "role": "owner" }
• Behavior: Updates only the join table row. Requests attempting to modify global target entity fields are rejected.

5. Delete / Unlink (DELETE /{parentPath}/{parentId}/{subResourcePath}/{targetId})

Removes the record from the pivot table, breaking the relationship without deleting either target or parent entities.

Independent Entity Lifecycles

To ensure data safety and separation of concerns, M:N sub-resource actions enforce strict Independent Entity Lifecycles:

• Pre-existing Entities Required: Parent and Target entities must already exist in the database before invoking a POST link action.
• No Nested Creation: Sub-resource endpoints do not accept nested object payloads to create target entities on the fly. The target entity must first be created via its top-level resource endpoint (e.g., POST /users).
• No Cascading Deletion: Executing a DELETE action on an M:N sub-resource removes only the pivot table link row. It explicitly does not delete the target or parent entity.

---

Query Actions

API Now! provides two distinct query endpoints depending on your application’s filtering and searching requirements:

List (GET Collection)

The most common query endpoint, used to fetch standard, ordered lists of records (e.g., loading products in a category or listing a user’s notes).

• Request Method: GET /{collectionPath} (e.g., GET /posts)
• Under the Hood: Uses GET query parameters (e.g., /posts?status=active&sort=-created_at).
• Filtering & Sorting: Only properties exposed in the entity’s Pagination Contract can be filtered or sorted.

Search (POST Search)

A specialized endpoint for complex logical queries and full-text keyword searches.

• Request Method: POST /{collectionPath}/search (e.g., POST /posts/search)
• Under the Hood: Unlike the List action, the Search action accepts a JSON request body representing the Abstract Syntax Tree (AST) of the query. This body allows clients to construct complex, nested query logic (using nested and/or groups).
• Filtering & Keyword Search: Filtering is restricted to properties exposed in the entity’s Pagination Contract. Keyword/substring searches (using the contains operator) are only permitted on text properties marked with the Search Indexed (search) checkbox in the Data Modeler UI.

---

API-Level Pagination & Query Contracts

Rather than configuring pagination and filtering on a per-action or per-endpoint basis, API Now! defines these properties at the API and Exposed Entity levels to ensure consistency and enforce performance limits.

1. Global API Pagination

Pagination is configured globally at the API level. The entire API uses the same pagination strategy. You cannot configure different pagination strategies per endpoint or action.

• Pagination Strategies:
  • offset: Traditional page-based pagination (uses page number/offset and page size).
  • cursor: High-performance, token-based pagination (uses an opaque cursor pointing to the last retrieved record, ideal for infinite scrolling).
• Page Limits: The global configuration defines the default page size (defaultLimit) and the maximum allowed page size (maxLimit) to prevent server overloads.

2. Entity-Level Query Contracts

For each exposed entity, you configure a Pagination Contract that specifies which properties are exposed to the client for query operations:

• Filterable Fields: The properties clients are allowed to filter by (e.g., status[eq]=active).
• Sortable Fields: The properties clients can sort by (e.g., sort=-created_at).
• Searchable Fields: The properties against which clients can perform text search queries.

Note

Only properties that have been marked as Indexed (index) or Primary Key (primary) in the Data Modeler UI can be added to the entity’s Pagination Contract for filtering and sorting. For searching, properties must be marked as Search Indexed (search).

---

Field Projections

To optimize network payloads and protect sensitive data, you can configure Field Projections in the API Modeler for all read-oriented actions: Read (GET resource), List (GET collection), and Search (POST search).

Field projections allow the API author to specify exactly which properties of the entity are returned to the client.

Projection Types

You can configure one of two projection strategies for each action:

1. Include Projection (include): Specify an allowlist of properties to return. Any property not explicitly listed is omitted from the response.
2. Exclude Projection (exclude): Specify a blocklist of properties to hide (e.g., hiding password hashes or internal status fields). All other properties are returned.

JSON Path Projections

Projections fully support nested JSON properties using dot-notation. This allows you to prune flexible JSON columns and return only the specific nested keys required by the client:

• Including a nested JSON key: Specifying settings.notifications.email in an include projection will return a pruned JSON object containing only that nested path, omitting other keys like settings.theme.
• Excluding a nested JSON key: Specifying settings.security.ipAllowlist in an exclude projection will return the JSON object with the IP allowlist property removed, keeping the rest of the object.

Tip

Using JSON path projections reduces payload size and ensures secure data transmission by preventing clients from accessing nested JSON data they don’t need.

---

Action Roadmap & Feedback

While our standard CRUD and Query actions support the vast majority of HTTP use cases for modern applications, we are always looking to expand our action suite.

If your application has a specific use case requiring custom actions or specialized flows (such as bulk imports, batch updates, or RPC-style actions) that are not covered by the current options, please let us know! We build API Now! based on real-world developer needs and welcome your feedback to guide future action additions.