Quick Reference
Quick Reference
lac31
Prerequisite:
You have a basic familiarity with CA Live API Creator
.Basic API Creator usage is illustrated by the learnings that start automatically when you first use API Creator. This article provides various quick-reference indices to frequently accessed topics. You can access detailed internal javadoc by downloading the .
In this article:
Resource Endpoints
RESTful resource endpoints are determined from the objects shown in the following table.
CA Live API Creator
provides all of the resource endpoints, except custom.Type | Obtained from | Programming Notes |
Base Table | Schema | CA Live API Creator reads the 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:
|
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 | API 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 and resources and to authenticate a user. For more information, see System REST Endpoints. |
JavaScript Extension Points
The following extensibility services are included. 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.
The following table lists the JavaScript extension points that are included:
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:
|
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:
|
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 the event handlers you can use to complement your rules, see Event Handlers. |
Custom authentication provider | Connect to corporate security. | API Server
For more information about custom authentication providers, see Create Custom Authentication Providers using JavaScript. |
JavaScript Context Variables
Your JavaScript has access to the pre-supplied libraries and to your own extensions. The following context variables are set when
CA Live API Creator
invokes JavaScript logic:For more information:
- About the rules syntax, see Rules syntax.
- About the libraries, see Logic Libraries.
Variable | Description | Applies to |
| 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) |
| For printing to the log, accessed by way of helpers, for example:
| All |
| For printing to sys out, for example:
| All |
| The
object provides access to the HTTP request, including API key, resource name, arguments, etc. Access the latter as for arguments supplied as .
For more information about the request object, see The Request Object. | All |
| The row object you are inserting/updating/deleting/retrieving.API Creator creates your JavaSCript object model automatically from the schema. This provides access to attributes and related parent objects. | Logic |
| Prior values of the object being updated. This is only defined for updates.
Provides access to attributes and related parent objects. | Logic |
| Provides access to containing row instance | Resources |
| Provides access to the database record after security applied, changes ignored. | |
| Provides access to the containing row instance in a resource event. | Resource row events |
| Provides access to the resource object. | Resource row events |
object | This object includes useful functions for manipulating resources.
For more information about the
object, see The SysUtility Object. | All |
| 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
. In a request event (response), this is a Java object accessible to JavaScript of the outbound JSON.For more information about the variable and how CA Live API Creator invokes request events (request and response), see Event Handlers. |
Services
You can use the following engine services for additional interaction:
Engine Service | Description |
The
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
object | methods are pre-supplied methods identified by a leading . You can use system methods in actions, validations, and formulas.
For more information about the
methods, see Rule Types. |
Admin data | Metadata services.
For more information about the admin data engine service, see System REST Endpoints. |
The
object | You can use this JavaScript object to retrieve a resource or invoke another REST service.
For more information about the
object, see The SysUtility Object. |
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 the
LogicContext
object or by way of REST.API | Description |
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. For more information about RESTful access, including the difference between accessing data using the LogicContext object and REST, see The logicContext Object. |
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:
- About how to use expressions, including illustrating the patterns, see the Reactive Logic Tutorial.
- About the reactive logic patterns, see Logic Patterns.
- About how to specify your business rules, see Logic.
- About JavaScript events, see Reactive Logic.
- About the JavaScript object model, see Customize your API.
- About the log, see View Logging Information.
- About topics, see Manage Topics.
The following table lists the rule/logic types:
Rule/Logic Type | Description | Example |
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:
Derive product_billofmaterials.value as:
Derive
as:
| |
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:
| |
Derive parent attribute value by summing designated child attribute, with optional child qualification condition. | Derive Customer.balance as:
| |
Derive parent attribute value by counting designated child rows, with optional child qualification condition. | Derive Customer.big_order_count as:
| |
Derive parent value as the min/max of designated child rows, with optional child qualification condition. | Derive Customer.maxOrder as:
| |
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:
| |
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:
For more information about commit validation, rule/logic type, see the Reactive Logic Tutorial. | |
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. | |
Copy one or more source rows to a
class. Useful for auditing, deep copy. |
| |
Allocates a provider amount to recipients, creating allocation objects (a provider / recipient junction) for each such allocation. |
| |
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, and 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 email, start business processes, send updates to other systems, etc. |
Returns a filtered, sorted collection (used in events). |
|
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
values, but userow.attribute
values. You can specify state transition logic (for example, logic based on data changes) using formulas, validations, and actions.oldRow.attribute - 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.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 haveCA Live API Creatorrecompute your rules when/as it detects null vales, see Synchronize Data with Logic.
- The
objectlogicContext.Provides access to runtime services and state, such as
,logicNestLevel
, and services to create, read, update, and delete rows.setUseCaseName
For more information about the
object, see The LogicContext Object.logicContext
- Logic design patterns.Use these patterns to meet most requirements, which leverage forward chaining.For more information:
- About learning reactive logic, see Reactive Logic Tutorial.
- About logic patterns, see Logic Patterns.
- About theSysLogicobject, see The SysLogic Object.
- 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.For more information:
- About extensibility, see Extensibility.
- About the logic libraries, including how to add user libraries and start using its facilities in your rules, see Logic Libraries.
- 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 the SQL commands in Database Connectivity.
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 resources | Alias and projection provide mapping and transformation logic. | API definition agreement with partner or internal system does not conform to SQL schema. |
Multi-table resources | Support business transactions with more than one row type. | Order with a list of items. |
tag | Additional 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 logic | Applied uniformly over all requests | Unlike 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 utilities | APIs to issue REST calls, including creating resource instances | Create a resource instance that corresponds to a Partner API agreement, and post it.
For more information about how to invoke APIs from other systems using the REST utilities service, including the
object, see Integrate Systems and Data. |
Troubleshooting
- For general troubleshooting, see Troubleshooting.
- For information about how to debug logic, see Debug.