Manage Functions

You can define your own RESTful endpoints by way of functions. You manage functions by creating them, importing them, exporting them, and deleting them.
calac41
You can define your own RESTful endpoints by way of functions. You manage functions by creating them, importing them, exporting them, and deleting them.
Functions can:
  • Call JavaScript that is defined in API Creator and return a JSON response.
  • Declare explicit arguments.
  • Pass rows automatically. Set some fields and
    CA Live API Creator
     updates the row (including relevant reactive logic). Instead of getting, altering, and saving a row by having to issue APIs, use a function function.
CA Live API Creator
 includes functions in your Swagger API documentation.
In this article:
3
Function Types
You can define the following types of functions:
  • Top-level functions
    Top-level functions are functions that are not associated to a table, view, or table-based resource. By default, functions are top-level functions. Use top-level functions to define any logic or service operation as endpoints.
  • Resource-oriented functions
    Resource-oriented functions are functions that are associated to a table, view, or table-based resource. They are operations on a table, view, or table-based resource row. Resource-oriented functions can access individual records in the function's JavaScript code using the current table 
    row
     object. 
    CA Live API Creator
     makes the row available to the function and any arguments. The function can then operate on the row (for example, 
    sendMail
     to alert a colleague about an Order), including update (for example, 
    giveRaise
     to an employee based on a 
    percentRaise
     argument).
    Resource-oriented functions advance the API interface from create, read, update, and delete (CRUD) operations to operations the application requires. You can regard resource-oriented functions as the methods that encapsulate your business logic. Reactive logic ensures that your API behavior is reused over all verbs (PUT, POST, and DELETE) for tables, views, and table-based resources. This behavior contributes to a separation of concerns (SoC). Client development can enforce data integrity by proceeding based on the API interface, in parallel with API Server logic.
Create Functions
Create a New Function
  1. With your API open, in the Create section, click 
    Functions
    .
    If your API does not have existing functions, the Welcome to Functions page appears. If your API has existing functions, they are listed on the By function tab that displays by default.
  2. Complete one of the following options:
    • If you have not defined any functions, on the Welcome to Functions page, click 
      Create a Function
      .
    • If you have defined at least one function, on the By function tab, click
      Create Function
      .
    The Definition tab for the new function appears by default.
  3. Complete the following fields, and then click
    Save
    :
    Function name
    The name for the function. Enter a meaningful name for your function (or accept the default name).
    Code
    Defines the JavaScript code for the function. You can:
    • Access and insert example JavaScript code by clicking 
      Examples
       and then
       Insert
       for the JavaScript code example you want to insert.
      For more information about the JavaScript code examples that are available from the functions code editor, see Code Examples.
    • Code functions in JavaScript that reference JavaScript libraries and Java JAR files in your 
      classpath
      .
      For more information about the context variables that are commonly accessed in JavaScript code, see the "Commonly Accessed Context Variables in Function JavaScript Code" section.
  4. (Optional) Add one or more parameters to your function. Click the 
    Parameters
    tab, click 
    Add Parameter
    , complete the following fields, and then click 
    Save
    :
    Name
    The name for the parameter. Enter a meaningful name for your parameter (or accept the default name).
    Type
    Define the parameter type.
    Values:
     number, string, or boolean
    Default:
     string 
    Required
    Specify whether the parameter is required.
    Default:
     Cleared
    Comments
    Enter a description of the parameter. 
  5. (Optional) Define the function type. Click the
    Resources
    tab, complete the following field, and then click 
    Save
    :
    Function Type
    Defines the function type.
    Options:
    • Top-Level:
       Defines the logic or service operation for this function as endpoints. 
    • Resource-Oriented:
       Associates this function to a table, view, or table-based resource. In the code editor, enter the tables, views, and table-based resources to which this function applies. Enter the names on separate lines.
    Use the following syntax for tables and views:
    <data source prefix>:<table name>
    Default:
     Top-Level
    For more information:
  6. Describe the purpose of this function by defining comments and the return type that the function expects by clicking the
    Documentation
    tab.
     
    CA Live API Creator
    includes these comments and the return type in your Swagger API documentation.
  7. Save your changes.
Your function is created and is active.
Commonly Accessed Context Variables in Function JavaScript Code
You code functions in JavaScript. They can reference JavaScript libraries and any Java JAR files that you have added to your 
classpath
. Your function returns a JavaScript object, which  
CA Live API Creator
 converts to JSON or translates if you are using XML output.
Your functions can access the following variables:
Variable
Example
Notes
Parameters
var theRaise = parameters.percentRaise * (row.Salary/100);
Define your parameters.
For more information about how to define your parameters, see the "Create a New Function" section.
row
row.Salary += theRaise;
Row variable attributes are based on the column names for the table or view. Alias column names (or attributes) for resources are not available from the row variable.
For more information about Read/Write row access, see the "Resource-Oriented Functions - Read/Write Row Access" section.
req
var user = req.userIdentifier
 
SysUtility
var functionResponse = SysUtility.getFunction(eachTest.TestName, null);
See the
B2B.testB2BAll()
function.
The following image shows an example of the
giveRaise
function's JavaScript code (for the B2B sample):
Function_B2BGiveRaise.png
Resource-Oriented Functions - Read/Write Row Access
You can optionally associate functions with tables or table-based resources. API users can call these function only on rows to which they have at least Read access. In such cases, the code for your function can reference the
row
variable, as shown in the previous image. Note this is 
table
row.
CA Live API Creator
 provides the mapping and translation, for example column de-aliasing. You can use your function code over multiple table-based resources based on the same table.
You can also update the row in functions. When the function completes,
CA Live API Creator
 calls the associated logic. If 
CA Live API Creator
 does not detect errors, it persists the row to disk.
You cannot use the
logicContext
object in your functions. This object makes visible key aspects of logic execution.
For more information about this object, see The logicContext Object.
You can call resource-oriented functions from Data Explorer.
Example: Create a Function
You can create a function for the 
employees
 table and the explicitly defined 
EmployeeWithRaises
 resource that gives an employee a raise. The following code snippet shows the JavaScript code:
var theRaise = parameters.percentRaise * (row.Salary/100);
row.Salary += theRaise;  // runs logic, persists change row(s) to database...
return [ {"status": "Success"}, {"raise": theRaise} ];
This JavaScript code is from the 
Resource-oriented
 function code example. This example is also illustrated in the Business to Business (B2B) Give Raise example.
For more information:
Control Access to Functions
You can control access to your functions by setting function-level permissions for roles.
For more information about how to control a role's permission to call specific functions, see Role-Based Endpoint Access.
View your List of Functions
In the Create section, click 
Functions
. The functions you create are listed on the 
By function
 tab, using the following syntax:
<Function name>(<param1>,<param2>, etc.)
Call Functions
You can call functions in the following ways:
Call Functions as Endpoints
You can call functions using the function name, optionally with parameters, using the following syntax:
http://localhost:8080/rest/default/demo/v1/
gcd?n1=0&n2=0
Call Functions on Tables, Views, or Resources
Prerequisite: (Views) You have added a virtual primary key to the view. For more information about how to add a virtual primary key to a view, see Manage Views.
You can call functions on tables, views, or resources and pass arguments.
Use a URL with the following syntax:
.../v1/<data source prefix>:<table, view, or resource name>/1/<function name>
Examples
The following are examples of calling the
giveRaise
function:
http://localhost:8080/rest/default/b2bderbynw/v1/
nw:Employees/1/giveRaise?percentRaise=1
0
http://localhost:8080/rest/default/b2bderbynw/v1/
EmployeesWithRaises/1/giveRaise?percentRaise=10
Call Functions using the SysUtility.getFunction() Method
You can call functions by way of GET operations. You can call functions from within API Server (for example, from logic, libraries, and functions), using the 
SysUtility.getFunction()
 method, for example:
var parms = {parm1: 1, parm2: 2};
var functionResponse = SysUtility.getFunction("myfunction", parms);
Test Functions from the REST Lab
You can use the REST Lab to test your function. You can select top-level functions as an endpoint from the list. For resource-oriented functions, you can enter the URL directly.
For more information about how to test functions in the REST Lab, see Test your API Using the REST Lab.
Call Functions on Tables from Data Explorer
You can call resource-oriented functions in Data Explorer.
For more information about how to call functions on tables from Data Explorer, see Data Explorer.
Export Functions
You can save a function and its parameters as a JSON definition file to a download directory.
  1. On the
    By function
    tab, click the function that you want to export.
    The Definition tab opens.
  2. Click
    Export
    .
A JSON file that contains the exported function is downloaded. The syntax for the file name is
FunctionExport_<function name>.json
.
Import Functions
You can import a previously exported function into your API.
  1. On the 
    By function
    tab, click
    Import Function
    .
    The Import JSON window opens.
  2. Select the function JSON file that you exported, and then import the file.
    If the function name already exists, API Server appends
    _clone_
    and a timestamp to the duplicate function using the following syntax:
    <function name>_clone_<timestamp>(<param1>,<param2>, etc.)
The function is imported and displays in the list.