Creating APIs‎ > ‎Logic‎ > ‎

Row Objects

When you create an API project and connect to your database, API Creator reads the schema to build a JavaScript object model. API Creator automatically creates a row object type (class) for each base table. Rows are analogous to Object/Relational Mapping (ORM) services. The row object types provide familiar persistence and accessor functions, but they also provide the following basic services:

  • Persistence. Like Object-Relational Mapping (ORM) objects, these row object types are persistence-enabled. You can access attributes and related data using these row objects. You can handle the update events that these row object types expose in JavaScript.
  • Resource/object mapping. You make update requests by way of custom resources. API Creator shares the row logic over all custom resources by mapping (transforming) custom resources to rows.
  • Logic execution. When resources are updated, they automatically invoke the relevant Reactive Logic and Events you have defined.
  • Attribute/related object access. Rows are passed to your logic and events and provide access to attributes (row.OrderDate) and related objects (row.Customer.name).

In most applications, you will shape your API by defining custom resources. Custom resources provide multi-object retrieval and update.

For more information about how to shape your API by defining custom resources, see Customize your API.

The following diagram shows an API PUT/POST request containing a JSON document (the left-most object) that consists of an Order and possibly several Items:

Persistence

As ORM objects, API Creator can read and write rows to disk. This occurs in the following ways:

Submitted Rows Saved

Read, insert, update, and delete verbs and save changed rows, with logic enforcement.

Chained Updates Saved

Your logic may cause API Creator to retrieve and update related rows. For example, the previous diagram shows that Order and Item were submitted; logic caused an adjustment of a Customer, which API Creator saves.

Note: API Creator brackets requests into a transaction.

LogicContext Read/Write Services

API Creator does the following:

  1. Submits rows to your logic, for example, in JavaScript logic events.
  2. Passes these events the logicContext object, which provides APIs for reading any data in API Creator and altering it.
  3. Saves submitted/changed updates to rows to disk at the end of the transaction.

For more information:

Resource/Object Mapping

You make update requests by way of custom resources. Custom resources are mapped (transformed) to rows so that row logic is shared over all custom resources.

Request Event Processing

  1. API Creator invokes your request event handler, providing you an opportunity to reformat the JSON. For example, you can reformat the JSON or, for complex transaction handling, you can inject @metadata tags.
  2. API Creator creates table rows from each JSON row.
  3. One of the following occurs:
    • (PUT operations) API Creator retrieves the values not included in the JSON row (so the ensuing logic always sees a "full" row) and performs optimistic locking checks.
    • (POST operations, or rows designated with the insert @metadata action tag) API Creator generates the primary key (for example, OrderId) by inserting the row into the database.
      The
       value is cascaded into the foreign keys of contained rows (for example, OrderId is placed into each Item).

For more information:

Logic Execution

Rows are rich (not anemic) domain objects: they not only provide access to attributes and persistence, but they enforce your business logic. When client make Put/Post/Delete requests, API Creator enforces your logic as described in the following sections.

For more information about logic execution, see Logic Execution.

Logic Phase Processing

For each row, your reactive logic is invoked automatically, based on what changed in a row. This may chain to update other related rows, for example, the Order may adjust the customer's balance. Logic invocation and ordering are system defined, which reduces errors and simplifies maintenance.

For more information about reactive logic, see Logic.

Commit Phase Processing

After all the rows are processed, and all of the derivations have been done, commit validations and events are executed. This enables you to specify logic such as "an order must have one or more items":
  1. Derive Order.itemCount as count(items)
  2. Commit Validation - Order.itemCount > 0

Logic Coding

In most cases, you specify your logic in server-side JavaScript. Your logic is passed key information required for its operation:
  • row, oldRow. The rows that were submitted or chained.
  • The logicContext object. Provides services to read/write other rows.

Your logic can read/write the row attributes and access related data.

For more information about server-side JavaScript events, including logic event rule types, see Logic Event Rule Types and Quick Reference.

Attribute/Related Object Access

Rows are passed to your logic and events and provide access to attributes and related objects. Row objects have the following behaviors:
  • Attributes. Rows have attributes for every column. For example, you can refer to an order's amount_total using:
row.amount_total
  • Parent Role Accessors.  Rows provide accessors to parent data
var department = row.headDepartment;     // head department for current department row
var deptName = row.headDepartment.name;  // or, data in the row
  • Child Role Accessors. Rows provide role accessors. You can refer to an orders' row.customer.balance or obtain a collection of row.lineitems (a collection of line item rows).
    var worksForEmps = row.reportingEmployees;  // child role name  
    for (var eachEmpNo in worksForEmps) {
        var eachEmp = worksForEmps[eachEmpNo];
        logicContext.logDebug(eachEmp);
    }

You can get code completion access to row attributes and role accessors using the API Creator JavaScript code editor. Note that, if there can be a large number of child rows (more than a few thousands), you should be careful about iterating over them like this, since it could use up a significant amount of memory and CPU.

For more information:

Debugging

You can show attribute values for logging and debugging using the toString() method.

For more information about logging and debugging, see Debugging.

Metadata Access

Logic context is passed to your rule and events. It provides methods to returns the description of the row, useful for extension services seeking to deal with rows generically.