Row Objects

When you create an API and connect
Layer7 Live API Creator
to your database,
Layer7 Live API Creator
builds a JavaScript object model and creates a
row
object type for each base table. For example, the
Demo
API sample includes the
customer
and
purchaseorder
objects. These objects provide familiar persistence and accessor functions. You can think of them as Object-Relational Mapping (ORM) objects: the object model provides access to attributes and related objects, read/write persistence services, and logic enforcement. They are key objects in API and logic processing.
Layer7 Live API Creator
updates the JavaScript object model automatically (for example, if you change the schema) when you reload your schema.
In this article:
2
In most applications, you shape your API by explicitly defining resources in your API. These resources provide multi-object retrieval and update.
The following diagram shows an API PUT/POST request containing a JSON document (the leftmost object) that consists of an order and possibly several items:
resource row logic.png
Persistence
Like ORM objects,
Layer7 Live API Creator
persists these
row
object types. You can access attributes and related data using these
row
objects. You can handle the update events that these object types expose in JavaScript.
As ORM objects,
Layer7 Live API Creator
reads and writes rows to disk. The read/write occurs in the following ways:
  • Layer7 Live API Creator
    saves submitted rows
    READ, INSERT, UPDATE, and DELETE verbs and save changed rows, with logic enforcement.
  • Layer7 Live API Creator
    saves chained updates
    Your logic can cause
    Layer7 Live API Creator
    to retrieve and update related rows. For example, the previous diagram shows that
    Layer7 Live API Creator
    submitted Order and Item. It also shows that logic caused an adjustment of a Customer, which
    Layer7 Live API Creator
    saves.
    Layer7 Live API Creator
    bundles PUT/POST/DELETE requests into transactions.
  • Layer7 Live API Creator
    does the following:
    1. Submits rows to your rules, for example, event rules.
      For more information about these rules, see Event Rule Types.
    2. Passes these rules the
      logicContext
      object, which provides APIs for reading data in
      Layer7 Live API Creator
      and altering it.
      For more information about this object, including persistence, see The logicContext Object.
    3. Saves submitted/changed updates to rows to disk at the end of the transaction.
Resource/Row Mapping
The
row
object type provides resource/row mapping. You make update requests by way of resources that you explicitly define in your API.
Layer7 Live API Creator
shares the row logic over all these resources by mapping (transforming) them to rows.
For more information about how to define resources explicitly in your API, see Customize your API.
Request Pipeline Processing
For more information about about how API Server invokes request pipelines, see Pipeline Events.
Logic Execution
The
row
object type provides logic execution. Rows are rich, not anemic, domain objects. They provide access to attributes and persistence and enforce your business logic. When the client makes REST PUT/POST/DELETE requests, they invoke the relevant rule and request events that you have defined.
For more information:
Logic Phase Processing
For each row,
Layer7 Live API Creator
invokes your reactive logic automatically based on what changed in the row. Reactive logic can chain to update other related rows, for example, the Order can 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
Layer7 Live API Creator
processes the rows and completes the derivation rules, it executes commit validation rules and event rules. In this way you can specify logic such as "an order must have one or more items", for example:
Derive Order.itemCount as count(items)
Commit Validation - Order.itemCount > 0
Logic Coding
Typically you specify your logic in server-side JavaScript.
Layer7 Live API Creator
passes key information required for its operation to your logic:
  • row
    ,
    oldRow
    . The rows that were submitted or chained.
  • The
    logicContext
    object, which 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 event rules, including the event rule types, see Quick Reference Guide.
Attribute/Related Object Access
The
row
object type provides attribute/related object access.
Layer7 Live API Creator
passes rows to your rules and resource events and provides access to attributes (
row.OrderDate
) and related objects (
row.Customer.name
).
For more information about the
row
object in resource events, see Manage Resource Events.
Row objects have the following behaviors:
  • Attributes.
    Rows have attributes for every column. For example, you can refer to an order's
    amount_total
    attribute using
    row.amount_total
    .
  • Parent role accessors.
    Rows provide accessors to parent data, for example:
    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 JavaScript code editor in API Creator.
    For more information:
    Use caution when iterating over child rows using the
    row
    object. This method can use up a significant amount of memory and CPU.
Show Attribute Values for Logging and Debugging
You can show attribute values for logging and debugging using the
toString()
method.
For more information about logging and debugging, see Debug.
Metadata Access
Layer7 Live API Creator
passes the
logicContext
object to your rules and events. This object provides methods to return the description of the row, useful for extension services that seek to deal with rows generically.