• • Scopes

A scope is a range in which a variable can exist. Every API XL document has a default global scope for the whole document. In addition to that, explicit scopes can be defined using the Scope element.

There are two main types of scopes for variables: document and block.

• Document Scoped Variables

Variables that are document scoped exist within either a global or explicit scope in the document. These variables will exist for as long as the code is within that particular scope, and can be accessed using dynamic expressions by any code within that scope.

Variables are assigned to a document scope using the SetVariable element. If there are multiple scopes, the variable is always assigned to the nearest parent scope.

• Block Scoped Variables

There are certain elements that create special scopes for very specific elements. A good example would be the Response element, which provides a variable containing the HTTP Response. That response variable exists with the block scope of the Response element and is not assigned to any document scope. When the element creating the block scope has finished processing, the variable is discarded.

Block scoped variables are assigned to that scope automatically by API XL in the specific cases it is used. Other variables cannot be assigned to a block scope. Any uses of the SetVariable element within a block scope ignore it and instead assign the variable to the appropriate document scope.

Block scoped variables can be re-assigned to the appropriate document scope using the SetVariable element.

• Structure

Dynamic Expressions have two main components: a prefix and a value. The prefix is a declaration that tells API XL what type of expression is being used. The value is then evaluated according to that type of expression to produce a final value. That final value, whatever its type, is then used when the API XL element with the expression is evaluated.

For example, an OGNL expression would be: “ognl:expressionHere”.

• Variable Access

All variables, temporary and permanent, that exist within the current scope are automatically made available in Dynamic Expressions. Simply refer to the variable by name, and its value will be used in the expression.

While any variable can be used in any expression, it is important to always be aware of the variable’s data type. While API XL might not restrict the use of variables in expressions, if the variable’s value doesn’t support being used in that type of expression, the expression, and the entire API XL process will fail.

Lastly, all variables are referenced with their own prefix character. This character varies depending on the type of expression language being used.

• OGNL

Object Graph Navigation Language, or OGNL, is a mechanism of executing Java code without needing the compiler or JVM. It provides the full power of the Java language and is an incredibly powerful way of writing expressions.

OGNL can be used in API XL in much the same way it can be anywhere else in the PilotFish application. The one exception is it cannot access Transaction Attributes or other application values from within API XL.

OGNL variables are prefixed with a “#” sign, such as “#variableName”.

Example: “ognl:#variable.getValue()”

• XPath

XPath is a mechanism of accessing and manipulating XML nodes. Since data returned from HTTP Requests is frequently already in (or can be transformed into, using API XL’s formatAs feature) XML, XPath expressions provide a powerful way of interacting with the contents of this data. Expressions such as iterating over NodeSets and retrieving String values are common when working with API XL.

An important thing to be aware of is how to handle namespaces when using XPath expressions in API XL. Namespaces can be referenced easily by a pre-configured prefix, which is built in the Configuration section. Please see the section on XPathNamespaces for more information about how to configure them.

XPath variables are prefixed with a “$” sign, such as “$variableName”. XPath expressions can only work on variables that are XML-based objects, such as Documents, Nodes, and NodeSets.

XPath 3.1, based on the Saxon specification, is what is used in API XL. A few important points to be aware of:

• Always reference the root NodeWhen writing an XPath expression from a variable, unless using a relative path, you must always reference the root Node:“$variableName/RootNode/Etc”. Example: “xpath:$response/ROOT/Entry”.

Note: When evaluating an XPath expression against PilotFish’s JSON-XML schema, the JSON-XML namespace will already exist under the “json” prefix in the API XL configuration.

• Configuration

Certain re-usable global settings can be configured at the beginning of an API XL document. This is handled by the elements in the Configuration category.

• HTTP Methods

The core of API XL is being able to execute HTTP requests using the full range of options in the HTTP specification. This is accomplished through the HTTP Method elements. There is one for each HTTP Method within API XL.

• General Workflow

These are elements that assist with building the overall workflow of the document. Things like iteration, variables, output, and more, all fall into this category. API XL offers a very wide range of elements to allow for an extremely flexible workflow.

• Utility

Utility elements include logging and exception handling. These are simply additional features that can assist with debugging and edge cases that might be encountered.

• XPathNamespaces

API XL supports XPath as a type of dynamic expression, and XPath expressions frequently need to support namespaces. In order for API XL to be able to evaluate namespaces, the namespaces must be configured. Specifically, a prefix that will be used by the expression must be bound to a URI.

The XPathNamespaces element in the Configuration section performs this function. It contains several child XPathNamespace elements that assign prefixes and URIs that are used in XPath evaluation. An unlimited number of XPathNamespace elements can be configured, each one with its own unique prefix and URI.

The XPathNamespaces element is built as follows:

The XPath expression that uses this namespace is:

xpath:/myns:Root/myns:Value

For more information about XPath expressions, see the appropriate section in this guide.

Note: When response data is serialized into XML from JSON, it will be done using PilotFish’s JSON-XML schema. To fully support this schema, the JSON-XML namespace will be automatically configured using the “json” prefix, no additional configuration is required.

• Authentications

Multiple web calls may need to re-use the same authentication scheme. These authentications can be configured here in advance. Each authentication is assigned a unique name, from which it is referenced from each HTTP call.

Currently, the only authentication supported in this section is Basic Authentication. Other types, such as bearer tokens, need a Header provided in the actual HTTP call.

• Certificates

Certificates is how KeyStore/TrustStore configurations are added. If certain HTTP calls need to have access to specific SSL certificates stored in KeyStores/TrustStores, this is how they are provided.

The Certificates element wraps around any number of child Certificate elements. Each individual Certificate element has a “name” attribute that defines a unique name that this configuration will be referenced by later on. It also has up to two child elements: a KeyStore element, and a TrustStore element, for storing the unique configurations for each.

The Certificates section, and its child Certificate elements, looks like this:

The KeyStore and TrustStore elements each have three attributes:

“type”: the type of the store, usually JKS.

“path”: a path to where the store is located on the filesystem. These paths must be explicit, full paths.

“password”: the password to access the store.

• HeaderGroups

When making a long series of HTTP calls, many of them may require the same specific headers to be provided. Rather than having to re-configure these headers each time, it is possible to define a global HeaderGroup.

A HeaderGroup, like the other configuration items, has an attribute called “name”, which defines a unique name by which it is referenced elsewhere in the document. A HeaderGroup can contain any number of Header elements as its children. When referenced in an HTTP Request, all the Header children and their values will be added to that request.

The HeaderGroups section, the child HeaderGroup elements, and its child Header elements looks like this:

Please note that HeaderGroup is evaluated at the point it appears in the document, so any dynamic expressions are evaluated at that point as well.

• Available Method Types

Currently, API XL supports the following HTTP Methods: GET, POST, PUT, and DELETE.

• Method-Declaration Attributes

When first declaring an HTTP method element, there are up to three attributes that can be assigned to it (one is required, the other two are optional). They are:

“url”: This is the only required attribute, as you can’t make an HTTP request without a URL. This URL should not include query parameters. They need to be entered separately as part of the QueryParams element.

“auth”: If an authentication configuration from the Configuration section is required, it is referenced by name here.

“cert”: If a Certificate configuration from the Configuration section is required, it is referenced by name here.

An example of a fully configured HTTP Method:

• Building the Request

The first child element of an HTTP Method element is the Request element. As the name suggests, the Request element is responsible for building and configuring the HTTP request. This request can be configured with any combination of QueryParams, Headers, and body Content. If none of these things are required, it can be left blank.

IMPORTANT: Even if no configuration is required for the request, the Request element is always required as the first child of any HTTP Method element. Its presence tells API XL that it’s time to execute the request, and nothing will happen without it.

• Handling the Response

Once the HTTP Request has been sent, in many cases an HTTP Response will be sent back from the server. This response is handled by another child element of the HTTP Method element, the Response element. Within the scope of the Response element, the HTTP Response is available to be handled in almost any way the user might need to. Some examples include writing to Output, retrieving specific values from its content, or using it to start new HTTP requests.

This is an example of the Response element:

• SetVariable

The SetVariable element is the primary means of storing values inside of variables. SetVariable only stores permanent variables, and it stores them in whatever the immediate enclosing scope is (by default, there is a global Scope even if one is not explicitly defined). All variables stored by this element are accessible via Dynamic Expressions elsewhere in API XL.

Variables are all named uniquely, and can be reassigned simply by setting a new value to that variable name. However, it is important to avoid accidentally overwriting a variable by setting a value to an existing variable name.

Variable values can also be Dynamic Expressions, and they frequently are.

SetVariable can be used in nearly any location throughout the API XL document. It has two attributes:

“name”: the name that will be assigned to the variable.

“value”: the value to assign to the variable.

Here is an example of SetVariable:

• Scope

Scope is an optional element related to using variables. By default, an implicit global scope exists around the entire API XL document. However, there can also be explicit scopes that can be defined to wrap around execution content. Once a Scope is defined, any variables that are set within that Scope exist only until that Scope is exited. Once outside of that Scope all variables assigned to it will be cleared.

Here is an example of a Scope:

• Output

The Output element is one of the most commonly used elements in API XL, because it provides the means to generate outputted content that can be handled by subsequent Stages in PilotFish Routes. The output is always in XML, however, it has an incredibly flexible structure.

Like several other elements, the Output element functions as an Execution Scope, meaning that any of the Execution-specific elements can exist as children of it. This is useful for building more complex structures by wrapping around other elements that will provide child content for the output document. For example:

• Condition

The Condition element is used to wrap around an If/Else conditional statement. The element itself functions as simply a wrapper, indicating that its child elements will specify the actual conditions to be tested. It has two types of child elements: If and Else.

If elements represent a single condition to test. This condition is provided via the “test” attribute, and is usually a Dynamic Expression. If this condition evaluations to “true”, then the child elements of the If are executed. Since If is another Execution Scope, any Execution-related API XL element can be a child of it.

>If elements can appear any number of times within a single Condition element, each time representing a different condition to test. The first If element that evaluates to “true” gets executed, all the others are skipped.

Else elements provide execution logic to perform if all other If elements have been rejected. The Else element MUST be the last item in order under the Condition element. Only if all If elements have evaluated to “false” will Else be executed.

Here is an example of a Condition element, with its If and Else children:

• Iterate

The most commonly used form of looping in API XL, Iterate simply runs a loop over a collection of elements. Iterate is also an Execution Scope, meaning all Execution-related elements can be placed within it. Each iteration exposes a new item within the collection to be handled by those child execution elements, and the loop stops once each item in the collection has been handled one time.

Iterate has two attributes:

“over”: this specifies the collection to iterate over. Generally, this is a variable accessed via a Dynamic Expression. All variables to iterate over must be either

• Java Objects that implement the Iterable Interface.
• Java arrays.
• XML NodeSets.

NOTE: A common case involves iterating over JSON arrays from an HTTP Response. API XL does not support special JSON handling. If the data needs to be handled, it should be converted into XML using the “formatAs” attribute (see Section 9.4.2) and iterated over using XPath.

“as”: this specifies the name of the temporary variable to expose the item within the collection so it can be accessed by child execution elements.

Here is an example of Iterate:

• While

Another form of loop, While simply executes a simple conditional test provided via its “test” attribute. While is also an Execution Scope, meaning all Execution-related elements can be placed within it. This test is usually a Dynamic Expression, and should access a variable whose value is changed at some point during the loop. As long as “test” evaluates to “true”, the loop will keep running.

Here is an example of While:

• For

The For element is another type of loop in API XL. It is an Execution Scope, meaning all Execution-related elements can be placed within it. For defines a starting index, an ending condition, and a change that gets executed for each iteration.

It has four attributes that must be populated to make it work:

“indexName”: the name of the temporary variable that the index value being tested in this loop should be assigned to.

“start”: the starting value of that temporary variable.

“condition”: the condition that should be evaluated on each loop, and once it evaluates as “false”, the loop should stop.

“change”: the change in the index value that should occur after each loop.

Here is an example of For:

• Log

The Log element allows for messages to be printed out to the PilotFish application’s log file. This is extremely useful for providing additional information to help debug the execution of an API XL document. Log has three attributes:

“message”: the message to print out to the log. This can be a specific String of text or a Dynamic Expression, for example, to print the value of a variable.

“exception”: if being used to log an exception, the actual Exception object can be passed here. In this case, the exception message and stack trace will be printed in the log. Handling exceptions is covered in the section on TryCatch.

“level”: by default, all log messages from the Log element have the DEBUG log level. This allows any level to be specified. Available levels, from lowest to highest, are:

• TRACE
• DEBUG
• INFO
• WARN
• ERROR
• FATAL

Here is an example of Log:

• ThrowException

The ThrowException element provides the ability to terminate the API XL execution by throwing an exception with a specific message. It has two attributes:

“message”: a message to pass along with the exception.

“cause”: if this should be thrown with another exception as its cause, the exception object can be passed in here.

Here is an example of the ThrowException element:

• TryCatch

The TryCatch element allows for handling exceptions within the API XL document. It provides the full capability of the common Try-Catch-Finally programming idium. The TryCatch element itself is simply a wrapper element around its Try, Catch, and Finally child elements. Each one of them can appear just once within a TryCatch element, but they are not all required in every use of it.

Here is an example of TryCatch. Each component of it will be explained in its own section:

• Status Code

The method for retrieving the Status Code from this object is:

int getStatus()

It returns an integer value, and can be handled using the following OGNL expression:

ognl:#responseVariable.getStatus()

• Headers

The method for retrieving the Headers from this object is:

Map<String,String> getHeaders()

It returns a Java Map, with Strings as both keys and values. Consult the Java documentation for handling Maps if more information is needed on how to handle this object. An example OGNL expression using this method is:

ognl:#responseVariable.getHeaders().get(‘Content-Type’)

• Contents

The method for retrieving the Contents from this object is:

Cache getContents()

It is returned as a PilotFish Cache object. API XL supports automatically formatting these objects into other types via elements that support a “formatAs” attribute. An example of OGNL expression using this method is:

ognl:#responseVariable.getContents()