Resource Row Events

Resource Row Events
lac42
CA Live API Creator
 executes the JavaScript code that is defined for a row event each time it retrieves a resource row from the database. You can control resource processing by defining resource row events that control the returned response values. You can create row events that delete rows, that add or drop attributes from the row, or that compute data.
Table-based resources and Free SQL resources can include row events.
For more information about the tasks that each endpoint type supports, see Customize your API.
In this article:
2
Create a Resource Row Event
Prerequisite:
The resource to which you want to add a row event exists.
  1. With your API open, in the Create section, click 
    Resources
    .
    A list of resources display.
  2. Select the resource for which you want to add a row event from the resource list, and then click the 
    Row Event
    tab.
    The row event page appears.
  3. Enter JavaScript code as the row event in the code editor. For more information about the variables that you can add to your row event, see the "Define your Row Event" section.
    You can access and insert JavaScript code examples into the row event code editor.
    For more information about the code examples that are available for row events, see JavaScript Code Examples.
  4. Save your changes.
Your resource row event is created.
Define your Row Event
You can use the following variables in your JavaScript code for your row event:
The row Variable
The 
row
 variable is the row the database retrieved. You retrieve values from it like any JavaScript object. You can change the values of the
row
variable, but the client sees data that does not correspond to what is actually in the database.
If you change the value of an attribute in the
row
variable, you cannot update this variable unless you override the
checksum
value.
You can also add new values, like a computed value.
Examples:
If you want only a specific customer to have the 
full_name
 attribute, composed of the customer's first name and last name, you can add a customers filter to a resource using the following syntax:
if (row.custnum === 1234) {
  row.full_name = row.first_name + ' ' + row.last_name;
}
You can also add the attributes using a more complicated JavaScript object or array, for example:
if (row.custnum === 1234) {
  row.name_info = {
    'First': row.first_name ,
    'Last' : row.last_name,
    'FullName': row.first_name+ ' ' + row.last_name
  }
}
Best Practice:
Use non-persistent attributes. For more information, see Manage Non-Persistent Attributes.
If you do not want 
CA Live API Creator
 to send the row to the client, you can filter out the row, for example:
if (row.username == 'DoNotShow') {
  row = null;
}
You can suppress individual items in a row from the output JSON using the following syntax:
if ('Ann' == row.username') {
  delete row.last_name;
}
CA Live API Creator
 records the attributes that you add to the
@metadata
section as
nonpersistent
CA Live API Creator
 records the attributes that you remove to the 
@metadata
 section as
removedAttributes
.
Best Practice:
 Use row/column security instead of deleting rows/columns. For more information, see Authorization and Role-Based Endpoint Access.
You can update rows only for table-based resources.
The tableRow Variable
The
tableRow
variable is the row that
CA Live API Creator
 reads from the database. It provides
CA Live API Creator
 access to the database record after it has applied security, and it ignores changes.
The parentRow Variable
If the resource is a subresource, and the API user is accessing it by way of its containing resource (for example, the API users is accessing the subresource using the 
/MyParent
 URL instead of directly using the 
/MyParent.MyChild
 URL), then the
parentRow
 variable is defined. The resource contains the parent row.
Do not alter the content in the parent row. The parent row is for reference only.
Example:
You can check if the
parentRow
variable is null using the following syntax:
// parentRow may be null, need to check first
if (parentRow) {
  row.full_name = parentRow.name + '.' + parentRow.name;
}
The resource Variable
The
resource
variable provides access to the resource object. 
CA Live API Creator
 passes the resource definition as this variable. This variable has the following methods:
  • getAttributes()
    returns a list of the attributes that are defined for this resource. Each attribute has a
    name
    , a
    columnName
    , and a
    format
    (if defined). 
  • getJoinCondition()
    returns a string, which contains the raw definition of the join to the parent resource, for example, 
    parent_ident = [ident]
    .
  • getName()
    returns the name of the resource, for example MyChild.
  • getNodalName()
    returns the full name of the resource, for example, MyParent.MyChild.
  • getTableName()
    returns the name of the table for which the resource was defined.
  • getTopResource()
    returns the top resource in the resource tree.
Example:
var i;
for (i = 0; i < resource.getAttributes().length(); i++) {
  var attribute = resource.getAttributes().get(i);
}
The req Variable
The
req
variable is available in the JavaScript code for rules and event handlers as the
req
object. This object describes the request that
CA Live API Creator
 is processing.
For more information about the
req
object, see The req Object.
Example: Use a Row Event
 The following example illustrates:
  • Skipping row
  • Accessing database row before aliasing.
  • Adding properties to output JSON.
  • Unicode usage.
  • Erasing value (property set to null).
  • Using property name that is not valid with dot syntax.
  • Non-persistent attributes property that
    CA Live API Creator
     adds to
    @metadata
    section.
    For more information about complex transaction processing, including how to use metadata action tags, see Complex Transaction Processing.
The following example uses the 
CustomerBusinessObject
resource that is in the
Demo
API sample.
Follow these steps:
  1. Open the Demo API.
  2. In the Create section, click
    Resources
    .
    A list of resources display.
  3. Select the
    CustomerBusinessObject
     resource from the list, and then click the 
    Row Event
    tab.
    The row event page appears.
  4. Enter the following JavaScript code as the row event into the code editor:
    if (row.name === 'Alpha and Sons') {
      // skipping a row 
      row = null;
    }
    else if (row.name === 'Bravo Hardware') {
      // Adding properties to output JSON 
      // Erasing value (property set to null).
      row.foo = 'Hi there!';
      row["2xbalance"] = 2 * tableRow.balance;
      row.credit_limit = null;
    }
    else if (tableRow.name === 'Charlie\'s Construction') {
      // show some love
      row.name = '\u2764 ' + tableRow.name + ' \u2764';
    }
  5. Test this resource row event in the REST Lab by clicking 
    Test
    .
  6. Observe the additional attributes and the
    @metadata
    changes for those affected rows.
For more information about how to test resource row events in the REST Lab, see Test your API Using the REST Lab.