Getting Started‎ > ‎

Quick Reference

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

Basic API Creator usage is illustrated by the 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 Endpoints

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

Type Obtained from Programming Notes
Base Table Schema API Creator reads schema to build the JavaScript 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:

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 use custom SQL and integrate non-SQL data by specifying resource types. Reactive logic and resource/object mapping govern updates.

For  more information:

  • About defining custom resources (custom REST resource endpoints) and resource types, see Customize your API.
  • About resource/object mapping, see Architecture.
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 endpointAPI Creator/Custom resources Use custom endpoints to create RESTful endpoints with potentially no relationship to the data model, indicate that requests to your custom endpoint require authentication, and can return JSON and other formats, such as HTML.
For more information, see Custom Endpoints.
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 services are derived from the underlying JavaScript object model. The extensibility services can invoke loadable logic libraries.

For more information about the extensibility services, see Extensibility.

JavaScript Event Type Description Applies to
Formula and validation logic Access if/else conditional flow, functions such as Date arithmetic, by specifying logic in JavaScript. Formulas and validations, based on the JavaScript object model.

For more information about formula and validation logic, see Formula Rule Type.

Logic event rule types 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 JavaScript object model.

For more information about logic event rule types, see Logic Event Rule Types.

Resource row events Invoked as each row is returned. For example, add attributes or filter the row. Resources, based on the JavaScript object model.

For more information about resource row events, see Resource Row Events.
JavaScript resource types 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 Define JavaScript Resource Types.

Custom endpoints Define new RESTful endpoint Resources with potentially no relationship to the data model. API Server

For more information about custom endpoints, see Custom Endpoints.

Request events Invoked for all requests. For example, to log requests or alter the request or response. API Server

For more information about request events, see Request Events.

Custom authentication providerConnect to corporate security.API Server

For more information about custom authentication providers, see Create Custom Authentication Providers using JavaScript.

For more information:

  • About JavaScript extension points and the extensibility services, see Extensibility.
  • About the JavaScript object model, see Customize your API.
  • About the logic libraries, including how to add user libraries and start using its facilities in your rules, see Logic Libraries.

JavaScript Context Variables

Your JavaScript has access to the pre-supplied libraries and to your own extensions. The following context variables are set when Live API Creator invokes JavaScript logic:

For more information:

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

For more information, see The logicContext Object.
Logic (the rule types listed in the "Reactive Logic" section)
log For printing to the log, accessed by way of helpers, for example:
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, for example:
out.println("message to log")
All
req The request object provides access to the HTTP request, including API key, resource name, arguments, etc. Access the latter as req.getUserProperties().get("argName"); for arguments supplied as arg.argName=true.

For more information about the request object, see The Request Object.
All
row The row object you are inserting/updating/deleting/retrieving.
Note: API Creator creates your JavaSCript object model automatically from the schema. This provides access to attributes and related parent objects.

For more information about the row object, see Row Objects.
Logic
oldRow Prior values of the object being updated.
Note: 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 events

For more information about resource row events, see Resource Row Events.
parentRow Provides access to the containing row instance in a resource event. Resource row events
resource Provides access to the resource object.  Resource row events
SysUtility object This object includes useful functions for manipulating resources.

For more information about the SysUtility object, see The SysUtility Object.
All
json In a request event (request), this is the raw Java string of the inbound content that the client sends. Create a real JavaScript object using String(json). In a request event (response), this is a Java object accessible to JavaScript of the outbound JSON.

For more information about the json variable and how Live API Creator invokes request events (request and response), see Event Handlers.

Services

You can use the following engine services for additional interaction:

 Engine ServiceDescription
The LogicContext object
This object is available in all JavaScript rules, and gives you access to a lot of information, and behavior.

For more information about the LogicContext object, see The logicContext Object.
The SysLogic object SysLogic methods are pre-supplied methods identified by a leading SysLogic. You can use system methods in actions, validations, and formulas.

For more information about the SysLogic methods, see Rule Types
Data formatting Reference for the formatting of numbers and dates.

For more information about the data formatting engine service, see Format Data in Rules.
Admin Data Metadata services.

For more information about the admin data engine service, see System REST Endpoints.
The SysUtility object You can use this JavaScript object to retrieve a resource or invoke another REST service. 

For more information about the SysUtility object, see The SysUtility Object.
@metadata action tags Additional attributes provide services for complex transaction processing.

For more information about complex transaction processing, see Complex Transaction Processing.

Data Access

Access data by way of simple persistence APIs using LogicContext, or by way of REST.

APIDescription
Persistence
Services to read, insert, update, and delete rows.

For more information about persistence, see The logicContext Object.
Rows Rows sent/received in object persistence. In addition to persistence, provide access to attributes and related objects.

For more information about rows API, see Customize your API.
RESTful Access Services for RESTful access to other servers, including important contrast between object/RESTful access.

Reactive Logic

You can express your transactional business logic for PUT, POST, and DELETE operations using reactive logic and JavaScript events. 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. Events are familiar, based on the automatically-created JavaScript object model by way of the row object.

Debug using the log and link your logic to user story behaviors/acceptance criteria using topics.

For more information:

The following table lists the rule/logic types:

Rule/Logic Type Description Example

Formula Rule Type

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 Rule Type

Derive child attribute value from parent attribute value.

Note: Changes to the parent attribute are not propagated to the child attribute.

Derive Lineitem.Price as:

 ParentCopy(product.price)
Sum Rule Type

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 Rule Type

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)
Minimum or Maximum Rule Type

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 Rule Type

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
Validation Rule Type

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 (for example, sums, counts).

Validate Purchaseorder.NotEmpty on commit as:

return row.item_count > 0

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

Managed Parent Rule Type

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.

InsertIntoFrom System Method
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)
allocateFromTo System Method

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");
Logic Event Rule Types

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 System Method

Returns a filtered, sorted collection (used in events).

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

Notes:
  • Rules syntax. Formulas, events, and validations must follow this syntax.
For more information about the syntax, see Rules Syntax.
  • Logic is unordered. The business logic engine invokes your rules automatically during transaction processing, ordered by their dependencies. API Server 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. You can specify state transition logic (for example, logic based on data changes) using formulas, validations, and actions.
  • Null values. You can check for null values.

For more information:

    • About null values and marking a formula as Just In Time (JIT), see Formula Rule Type.
    • About JIT, see the following Just In Time note.
  • Just In Time. You can specify derivation rules (formula, sum, count, and min/max) as JIT. If the value in the database is null, the rule fires on first retrieve and is stored in the database. This is useful, for instance, to recompute values without incurring the cost up front.
  • Note: Specifying derivation rules as JIT can affect performance whenever new values are computed on the fly.

    For more information about JIT, including how to specify to have Live API Creator recompute your rules when/as it detects null vales, see Synchronize Data with Logic.

  • The logicContext object. Provides access to runtime services and state, such as logicNestLevelsetUseCaseName, and services to create, read, update, and delete rows.
For more information about the logicContext object, see The LogicContext Object.
  • Logic design patterns. Use these patterns to meet most requirements, which leverage forward chaining.
For more information:
  • Extensibility. You can meet requirements not solved by core rules by defining rules that can invoke JavaScript. Judicious design can result in reusable logic, as illustrated by the pre-supplied BusinessLogic services for allocation and copy. You can add JavaScript as libraries (on the Create, API Properties, Libraries tab).
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:

Data Integration

For a description of the key services, see Integrate Systems and Data. For an example, see the Business to Business Example.

Service Summary Example
Custom resourcesAlias and projection provide mapping and transformation logic.API definition agreement with partner or internal system does not conform to SQL schema.
Multi-Table ResourcesSupport business transactions with more than one row type.Order with a list of items.
@metadata tagAdditional attributes provide services for complex transaction handling.Create or update existing data lookup parent data to set foreign keys by programming requests.

For more information:
Business logicApplied uniformly over all requestsUnlike Web applications where business logic might be unavailable in a button (controller code), logic is applied 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.

For more information about invoking APIs from other systems using the REST utilities service, including the SysUtility object, see Integrate Systems and Data.

Troubleshooting