Row Objects
Row Objects
lac42
When you create an API and connect
CA Live API Creator
to your database, CA Live API Creator
builds a JavaScript object model and creates a row
object type for each base table. Objects refer to the JavaScript objects created as part of the JavaScript object model. You can think of these objects as Object-Relational Mapping (ORM) objects. The object model provides access to attributes and related objects, read/write persistence services, and logic enforcement. For example, the Demo API includes the customer
and purchaseorder
objects. CA Live API Creator
updates this model automatically (for example, if you change the schema) when you reload your schema.The row object type provides familiar persistence and accessor functions.
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.
For more information about how to shape your API, see Customize your API.
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:

Persistence
The
object type provides persistence. Like ORM objects,row
CA 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,
CA Live API Creator
reads and writes rows to disk. The read/write occurs in the following ways:- CA Live API Creatorsaves submitted rowsREAD, INSERT, UPDATE, and DELETE verbs and save changed rows, with logic enforcement.
- CA Live API Creatorsaves chained updatesYour logic can causeCA Live API Creatorto retrieve and update related rows. For example, the previous diagram shows thatCA Live API Creatorsubmitted Order and Item. It also shows that logic caused an adjustment of a Customer, whichCA Live API Creatorsaves.CA Live API Creatorbundles PUT/POST/DELETE requests into a transaction.
- CA Live API Creatordoes the following:
- Submits rows to your logic, for example, in event rules.For more information about event rules, see Event Rule Types.
- Passes these rules thelogicContextobject, which provides APIs for reading data inCA Live API Creatorand altering it.For more information about thelogicContextobject, including persistence, see The logicContext Object.
- 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.
CA Live API Creator
shares the row logic over all these resources by mapping (transforming) them to rows.Request Event Processing
CA Live API Creator
processes request events using the following workflow:- CA Live API Creatorinvokes 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@metadatatags.
- CA Live API Creatorcreates table rows from each JSON row.
- One of the following occurs:
- (PUT operations)CA Live API Creatorretrieves the values that are not included in the JSON row (so the ensuing logic always sees a "full" row) and performs optimistic locking checks.
- (POST operations, or rows that are designated with the insert@metadataaction tag)CA Live API Creatorgenerates the primary key (for example,
) 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).OrderId
For more information:
- About viewing an example of reformatting the JSON, see the Advanced Topics section in the B2B API Sample.
- About generating the primary key, see Automatic Key Generation.
- About howCA Live API Creatorinvokes request event handlers, see Event Handlers.
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 PUT/POST/DELETE requests, they invoke the relevant reactive logic and events you have defined.
For more information:
- About logic execution, see Logic Execution.
- About the anemic domain model, see the Anemic domain model Wikipedia page.
Logic Phase Processing
For each row,
CA Live API Creator
invokes your reactive logic automatically based on what changed in a 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 all the rows are processed, and all the derivations have been done,
CA Live API Creator
executes commit validations and events. 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.
CA Live API Creator
passes key information required for its operation to you logic:- row,oldRow. The rows that were submitted or chained.
- ThelogicContextobject, 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 events, including event rule types, see Quick Reference Guide.
Attribute/Related Object Access
The row object type provides attribute/related object access.
CA Live API Creator
passes rows to your rules and resource row events and provides access to attributes (row.OrderDate
) and related objects (row.Customer.name
).For more information about the
object in resource events, see Resource Row Events.row
Row objects have the following behaviors:
- Attributes.Rows have attributes for every column. For example, you can refer to an order's
attribute usingamount_totalrow.amount_total.
- Parent role accessors.Rows provide accessors to parent data, for example:var department =row.headDepartment; // head department for current department rowvar deptName = row.headDepartment.name; // or, data in the row
- Child role accessors.Rows provide role accessors. You can refer to an orders'
or obtain a collection ofrow.customer.balance
(a collection of line item rows).row.lineitemsvar worksForEmps =row.reportingEmployees;// child role namefor (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:For more information:- About the JavaScript code editor, see JavaScript.
- About code completion, see Code Completion.
Use caution when iterating over child rows using the
object. This method can use up a significant amount of memory and CPU.row
Show Attribute Values for Logging and Debugging
You can show attribute values for logging and debugging using the
method.toString()
For more information about logging and debugging, see Debug.
Metadata Access
CA 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.For more information about this object, see The logicContext Object.