Docs‎ > ‎

Quick Reference

Prerequisite: You have a basic familiarity with Live API Creator.

Basic API Creator usage is illustrated by the key learnings that start automatically when you first use API Creator. This page provides various quick-reference indices to frequently accessed topics. You can access detailed internal javadoc by downloading the apidocs.zip.

Resource End Points

RESTful resource endpoints are determined from the objects shown in the following table. Live API Creator provides all of the resource endpoints, except custom.

For more information about defining custom REST resource endpoints, see Define Custom REST Resources.

Type Obtained from Programming Notes
 Base Table  Schema API Creator reads schema to build the object model with accessors for attributes and related objects, and logic events for Insert, Update, and Delete operations.

Reactive Logic: You can define transactional business logic.

For more information about the object model, see Define Custom REST Resources.

 Custom Resources API Creator/Resources Used to provide "document model" GET response JSON (for example, Customers with a set of Orders and a set of Addresses). Resources typically automate SQL, but you can specify resource types for custom SQL and to integrate non-SQL data. Updates are governed by reactive logic and resource/object mapping.

For  more information:

 View Table
Schema Used for complex SQL. Updates are not subjected to reactive logic.
 Stored Procedure  Schema Per security, you can access stored procedures using REST.
 Custom Endpoint JavaScriptUse Custom Endpoints to create RESTful endpoints with potentially no relationship to the data model.

Custom Endpoints have optional authentication, and can return both JSON and other formats, such as HTML.
 Logic Administration Objects  Built in APIs to obtain the list of tables, resources and to authenticate a user.

JavaScript Extension Points

Live API Creator provides the following Extensibility Services. Many of these are derived from the underlying JavaScript object model, created by Live API Creator when you connect to your database. These services can invoke Loadable Logic Libraries. You can complement your rules with JavaScript event handlers. You can implement behavior using JavaScript with custom endpoints.

Type Description Applies to
Formula and Validation Logic Logic is specified in JavaScript for access to if/else conditional flow, functions such as Date arithmetic. Formulas and validations, based on the object model.

For more information:

Logic Event Rule Type Invoke JavaScript action (often an extensible service); can execute during or after row PUT/POST/DELETE processing, or on commit (after all rows are processed). For example, you might want to send mail or start workflows on certain updates. Tables, based on the object model.

For more information:

Resource Row Event Invoked as each row is returned, for example, add attributes or filter the row. Resources, based on the object model.

For more information:

JavaScript Resource Type Materialize data using JavaScript, for example, by invoking REST services to build a request that integrates data from other systems. Resources

For more information about JavaScript resource types, see Create JavaScript Resource Types.

Custom Endpoints Define new RESTful endpoint Resources with potentially no relationship to the data model.

Custom Endpoints have optional authentication, and can return both JSON and other formats, such as HTML.
API Server

For more information about custom endpoints, see Create Custom Endpoints.

Request Events Invoked for all requests, e.g., to log requests or alter the request or response. API Server

For more information about request events, see Request Events.

Custom Authentication Provider Connect to corporate securityAPI Server

For more information about custom authentication providers, see Define a Custom Authentication Provider using JavaScript.

For more information:
  • About JavaScript extension points, see Extensibility.
  • About the JavaScript object model, see JavaScript.
  • About the logic libraries, including how to add user libraries and start using its facilities in your rules, see Logic Libraries.

JavaScript Context

Your JavaScript has access to Libraries, both pre-supplied and your own extensions. The following are set when JavaScript logic is invoked. For more information about the syntax, see Rules syntax.

Variable Description Applies to
 logicContext Services for creating, reading, updating and deleting rows. Provides information about key logic state, including verb, nest level.

Important! See the api documentation.
Logic (all rule types listed in the Live Logic section, below)
 log For printing to the log, accessed via helpers, e.g.,

log.debug("message to log; row: " + row);
log.finer("more verbose - but < finest");
log.error("more serious message");
logicContext.logDebug("msg with object"); // recommended
 all
 out For printing to sys out, e.g.

out.println("message to log")
 all
 req The request object provides access to the HTTP request, including ApiKey, resource name, arguments, etc.  Access the latter as req.getUserProperties().get("argName"); for arguments supplied as arg.argName=true  all
 row The row object being inserted/updated/deleted/retrieved (your object model is created automatically from the schema).

This provides access to attributes and related parent objects
 logic
 oldRow Prior values of the object being updated. This is only defined for updates.

Provides access to attributes and related parent objects
 logic
 containingRow Provides access to containing row instance  resources
 tableRow Provides access to the database record after security applied, changes ignored.  Resource Row Event
 parentRow Provides access to the containing row instance in a resource event.  Resource Row Event
 resource Provides access to the resource object.   Resource Row Event
 SysUtility JavaScript object used to retrieve a resource, or invoke another REST service.  all
 json In Request Event (Request) this is a Java String of the inbound content.  Use String(json) to create a real JavaScript object. In Request Event (Response), this is a Java Object accessible to JavaScript of the outbound JSON.
 

Services

You can use the following engine services for additional interaction:
 The LogicContext object
This object is available in all JavaScript rules, and gives you access to a lot of information, and behavior.
 System Methods Use system methods in actions, validations and formulas as required
 Data formatting Reference for the formatting of numbers and dates
 Admin Data Metadata services   
 SysUtility Useful functions for manipulating resources
 @Metadata Additional attributes provide services for Complex Transaction Handling

Data Access

Access data by way of simple Persistence APIs using LogicContext, or by way of REST.
 Persistence
Services to read, insert, update and delete rows
 Rows Rows sent/received in Object Persistence.  In addition to persistence, provide access to attributes and related objects.
RESTful Access Services for RESTful access to other servers, including important contrast between Object / RESTful access

Reactive Logic

The following is a summary of the reactive logic and JavaScript events you can use to express your transactional Business Logic for PUT, POST, and DELETE operations:

  • Events are familiar, based on the automatically created Object Model by way of the row object.
  • Reactive Logic is like a spreadsheet: you declare expressions for column derivations and table validations. API Creator watches for changes to referenced data, and reacts to adjust the referencing data - which can chain. The reactive logic tutorial explains how to use them, illustrating these patterns.

    For more information:
  • Use the Log for debugging - it depicts:
    • Rule Execution. Logs every rule that fires, including complete row state, with indenting to show multi-object chaining.
    • SQL. Use this to verify that SQL is expected.
  • Use Topics to link your Logic to User Story Behaviors / Acceptance Criteria.
Rule/Logic Type       Description Example

Formula

 

Derive attribute value using other attributes in that table, or parent table (changes are propagated).

For conditional assignment, use JavaScript if/else, or the ternary operator (? :).

Derive Lineitem.amount as

 return row.part_price * row.quantity_ordered

Derive product_billofmaterials.value as

return row.kit_number_required * row.product.price

Derive order.DueDate as

if (row.due_date === null) {
   return new Date(moment(row.placed_date).add('months', 1)
else
   return row.due_date; // no change

Parent Copy

Derive child attribute value from parent attribute value (unlike formula references, parent changes are not propagated)


Derive Lineitem.Price as

 ParentCopy(product.price)
Sum  

Derive parent attribute value by summing designated child attribute, with optional Child Qualification Condition

Derive Customer.balance as

Sum(ordersList.amount_un_paid where is_ready = true)
Sum(children where anAttribute != null)

Count

Derive parent attribute value by counting designated child rows, with optional Child Qualification Condition.

 Derive Customer.big_order_count as

Count(ordersList where amount_total > 100)
Min/Max

Derive parent value as the min/max of designated child rows, with optional Child Qualification Condition.

Derive Customer.maxOrder as

max(ordersList where is_ready = true)

Validation

Multi-attribute expression of class/parent attributes that must be met for a transaction to succeed (else exception is thrown); can execute as transaction rows are processed, or at commit time after all rows are processed.


Validate Customer.CheckCredit as:

row.balance < row.credit_limit
Commit Validation

Multi-attribute expression of class/parent attributes that must be met for a transaction to succeed (else exception is thrown); executes at commit time so your validation code sees the results of all rule executions for all rows (e.g., sums, counts).

 Validate Purchaseorder.NotEmpty on commit as:

return row.item_count > 0

more information about commit validation, rule/logic type, see the Reactive Logic Tutorial.


Managed Parent

Automatically insert a parent object if it does not already exist.

Create parent for GroupBy, for example, empsales to track total sales for employee each month.


InsertInto Copy one or more source rows to a target class. Useful for auditing, deep copy.   if (row.baseSalary != oldRow.baseSalary)
SysLogic.insertChildFrom(
"employee_audits", logicContext)

Allocation

Allocates a provider amount to recipients, creating allocation objects (a provider / recipient junction) for each such allocation.

 
SysLogic.allocateFromTo(
 logicContext,
 SysLogic.findWhere(row.paymentCustomer.ordersList,
    "row.amount_un_paid > 0", "placed_date a"), 
 "payment_order_allocations", 
 "amount_un_disbursed");

 Event
 

Invoke JavaScript action (often an extensible service); can execute during or after row processing, or on commit (after all rows are processed)


See the previous example.

Early Event

Invoke JavaScript action during row processing, before rule execution (formulas, events, validations)

Often used to compute primary keys.

Commit Event

Invoke JavaScript action after all rows are processed and all rules have fired

Often used to send mail, start business processes, send updates to other systems, etc.

findWhere

Returns a filtered, sorted collection (used in events)

 
SysLogic.findWhere(
    row.paymentCustomer.ordersList,
    "row.amount_un_paid > 0",
    "placed_date a")

Syntax

Formulas, events and validations must follow this syntax.

 

Notes:
  • Logic is unordered - The Business Logic Engine invokes your rules automatically during transaction processing, ordered by their dependencies. API Creator invokes the logic and calls the rules automatically when referenced data changes.

    For more information about rules, see Learning Rules.
  • Old Values - Formulas, Validations and Actions can reference not only row.attribute values, but use oldRow.attribute values, enabling you to specify state transition logic (for example, logic based on data changes).
  • Null values - Support is provided to simplify null value checking.
For more information, see Formula.
  • logicContext - Provides access to runtime services and state, such as logicNestLevel, useCaseName, services to create, read, update and delete rows, etc. For more information about the LogicContext object, see LogicContext object.
  • Logic Design Patterns - Use these patterns to meet most requirements, which leverage forward chaining.
For more information:
  • Extensibility - Rules can invoke JavaScript, enabling you to meet requirements not solved by Core Rules. Judicious design can result in reusable logic, as illustrated by the pre-supplied BusinessLogic services for allocation and copy.
For more information about extensibility, see Extensibility.
  • Performance - Adjustments are one-row "delta" updates, which require that stored values match the rule definitions. Ensure that your existing data is consistent with the rules, such as with SQL commands like this.
For more information:
  • About performance, see Performance.
  • About how to ensure data consistency with rules, see SQL commands, Data Sources.

Data Integration

For a description of the key services, see Data Integration. See the Business to Business Example.

Service Summary Example
 Custom ResourcesAlias and Projection provide mapping and transformation logicAPI definition agreement with Partner, or internal system, does not conform to SQL schema
 Multi-Table ResourcesSupport Business Transactions with more than one row typeOrder with a list of items
 @metadata tagAdditional attributes provide services for Complex Transaction HandlingProgram requests to create or update existing data.

Program requests to lookup parent data to set foreign keys.
 Business LogicApplied uniformly over all requestsUnlike Web Apps where business logic might be unavailable in a button (controller code), logic is applied the uniformly, regardless of whether the request is an interactive program, or another computer
 REST utilitiesAPIs to issue REST calls, including creating resource instancesCreate a resource instance that corresponds to a Partner API agreement, and post it.

Troubleshooting

For general troubleshooting, see Troubleshooting.
For information about debugging logic, see Debug your API Project.