Log out?

API XL – User Guide

PilotFish API XL User Guide

Table of Contents

  1. Introduction
  2. Use With XSLT
  3. Quick Overview
  4. Declaration
  5. Variables

    1. Scopes
    2. Document Scoped Variables
    3. Block Scoped Variables
  6. Dynamic Expressions

    1. Structure
    2. Variable Access
    3. OGNL
    4. XPath
  7. JSON-XML
  8. API XL Component Overview.

    1. Configuration
    2. HTTP Methods
    3. General Workflow
    4. Utility
  9. Configuration

    1. XPathNamespaces
    2. Authentications

      1. BasicAuthentication.
    3. Certificates
    4. HeaderGroups
  10. HTTP Methods

    1. Available Method Types
    2. Method-Declaration Attributes
    3. Building the Request

      1. QueryParams
      2. Headers
      3. Body.
    4. Handling the Response.

      1. Execution Scope.
      2. Response Attributes
  11. General Workflow

    1. SetVariable
    2. Scope
    3. Output

      1. Building The Output Document
      2. Passing in Values
      3. Formatting Output
      4. Manually Adding XML.
    4. Condition
    5. Iterate
    6. While
    7. For
  12. Utility

    1. Log
    2. ThrowException
    3. TryCatch

      1. Try
      2. Catch
      3. Finally
  13. Response Object API

    1. Status Code
    2. Headers
    3. Contents
  14. Supported Encodings
  • Introduction

API XL is an XML evaluation and execution system for making complex HTTP web calls. It primarily provides benefits when dealing with modern RESTful APIs, where a long series of web calls need to be chained together in a sequence. However, it can be used for any process involving HTTP calls.

API XL benefits from a powerful set of tools that can be used around the actual HTTP calls, such as flow control, iteration, conditional logic, exception handling, outputting data, etc. It also has the ability to simply and effectively express any web call needed.

This document will explain how to use all of API XL’s features so that this tool can be used effectively within the PilotFish application.

  • Use With XSLT

In many cases, API XL will be generated using XSLT in the PilotFish Data Mapper. In many ways, API XL is very similar in concept to XSLT: a series of special XML elements that provide instructions to a Processor that evaluates them. Because of how XSLT can dynamically build an output Format based on the values in an input format, it is ideal to use the Data Mapper to generate API XL using the data coming in.

However, it is important to always be aware that API XL and XSLT are completely independent of each other. They are each evaluated separately, by totally separate components. The XSLT created by the Data Mapper is evaluated during the XSLT Transformation stage, whereas the API XL is evaluated by a subsequent stage, usually the PilotFish API XL Transport.

This means that any XSLT instruction elements will only be used for creating the API XL document, and will not be present when the API XL is being evaluated. A good example would be iteration. An <xsl:for-each /> element will be used by the XSLT Transformation to produce XML output during its iteration. A <http:Iterate /> (covered later in this document) element will achieve the same iteration, but it will run only later when the API XL is evaluated.

The simple rule of thumb is that anything with the XSLT namespace prefix will only be present for the XSLT Transformation, while anything with the API XL namespace prefix will only be evaluated later on.

  • Quick Overview

This is a quick overview of what an API XL document looks like and the basic features of how it works. All of these elements will be explored in more detail.

(A): Every API XL document must start out with the standard root element and namespace declaration.

(B): Optional global configurations for things like authentications that will be re-used throughout the document.

(C)/(J): Convenience wrappers around all HTTP methods are provided for executing the individual web calls.

(D)/(K): HTTP Requests can be configured with Query Params, Headers, and Body.

(E): HTTP Responses can be handled very flexibly, including automatic conversion between data types to make the content easier to manipulate.

(F)/(I): Values can be stored in variables, and can be retrieved in different ways with different types of expressions.

(G): Outputting data is highly flexible, with no restrictions on what, where, or how many times Output can be written.

  • Declaration

To use API XL, a root element must be declared. This element must also have the API XL namespace.

  • Variables

In any procedural set of instructions, variables are a crucial part of the workflow. API XL has broad and flexible variable support. At any point in time, any value can be set as a variable, from a simple String to the entire contents of an HTTP Response. These variables can be of any data type, and can be accessed and manipulated using Dynamic Expressions.

  • 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.

  • Dynamic Expressions

Dynamic Expressions are primarily used to interact with variables, however they can also be used for other complex tasks as well. Dynamic Expressions can be placed into any attribute in any API XL element (any element with the API XL namespace).

API XL supports two separate Dynamic Expression languages: OGNL and XPath.

  • 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.

  • JSON-XML

PilotFish specializes in transforming a whole range of Formats to and from XML. One important format when dealing with APIs is JavaScript Object Notation, or JSON. The structures of JSON and XML are similar, however JSON has several constructs such as arrays that have no counterpart in XML.

To help make building a JSON structure out of XML easier, PilotFish has prepared a JSON-XML schema. This schema allows for precisely constructing a JSON payload in XML. JSON-XML is used in most places where JSON is handled in API XL. For more details on this schema, please consult the separate PilotFish documentation for JSON-XML.

Note: To help parse JSON-XML using XPath expressions, the JSON-XML namespace is added to the namespace configuration by default, bound to the prefix “json”.

  • API XL Component Overview

This is quick overview of the categories of components that are a part of the API XL structure.

  • 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.

  • Configuration

When making a series of HTTP calls, there are a number of repetitive components that are shared among multiple calls. These components can be configured in the Configuration section.

Configuration must be declared prior to Execution, as the configuration must be read and stored prior to the actual execution of HTTP web calls that wish to use the Configuration. A Configuration section looks like this (Its various child elements are optional):

  • 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.

  • BasicAuthentication

The BasicAuthentication element has three attributes that define its configurations.

“name”: The name of this authentication, which is the key that will be used to reference it from the HTTP calls later on.

“username”: The username to be added to the Basic Authentication string.

“password”: The password to be added to the Basic Authentication string.

An unlimited number of BasicAuthentication elements can be added as children of the Authentications element. The BasicAuthentication element looks as follows:

  • 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.

  • HTTP Methods

The core of API XL is the ability to execute HTTP calls using a variety of HTTP Method types. All HTTP Method elements have tag names that are identical to the name of the method that they represent. For example, <http:GET> represents an HTTP GET request. Other than the tag name, the content (attributes and body) of all HTTP Method elements is 100% identical.

Because the structure of the HTTP Method elements is identical across all of them, this section will be focusing on how to use them in general.

An example HTTP Method element looks like this:

  • 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.

  • QueryParams

In an HTTP URL, query parameters are appended to the end of the request URL. These parameters can be dynamically built in the Request via the QueryParams element.

Each QueryParams element wraps around any number of individual QueryParam elements. Each one of these QueryParam elements represents a single parameter to be appended to the URL. Each one has two attributes:

“name”: the name of the query parameter.

“value”: the value of the query parameter.

An example of the QueryParams section is:

  • Headers

Very often, custom headers will need to be provided for HTTP requests. This is done via the Headers section. A Headers element wraps around any number of child Header elements, each one representing an individual Header within the request. Each Header element has two attributes:

“name”: the name of the header.

“value”: the value of the header.

In addition to individually configuring headers here, HeaderGroups can also be referenced as well, using the HeaderGroupRef element. This element has a single attribute:

“ref”: the name of the HeaderGroup in the Configuration section that should be included here.

IMPORTANT: If a Header appears more than once in a Headers configuration, the headers are set in local-first order. A local Header takes priority over a Header from a HeaderGroup, for example.

An example of the Headers section is:

  • Body

The final piece of the Request configuration is the Body, or the message sent along with the request. API XL supports several different ways of building the Body in order to support a number of different content types. Regardless of the type of the content, a root Body tag is always required.

XML

XML is a common content type for request bodies. API XL supports building arbitrary XML structures within an XML element. Whatever child content is written in will be passed along as XML with the request.

Here is an example of XML:

JSON

JSON is another common content type for request bodies. API XL supports building arbitrary JSON structures within an XML element. Because the JSON is being built within an XML document, the PilotFish JSON-XML schema is used to construct it. Whatever JSON-XML content is written within the JSON element will be automatically converted to regular JSON and passed along as the body of the request. Pleae consult the JSON-XML section of this document for more details.

Here is an example of JSON:

Tokens

String tokens, or just Tokens for short, is how to build an arbitrary String message as the request body. Each Token element contains a fragment of a String that will be concatenated together into the full body message. This is useful for combining literal values with variables or other dynamic expressions. An optional encoding attribute can be set on Tokens to specify the String encoding.

Here is an example of Tokens:

Expression

Expression is similar to Tokens, but is designed to produce a single value from a dynamic expression. This is generally used to extract data from a single variable that needs to be passed along as the request body.

Here is an example of Expression:

FormUrlEncoded

The x-www-form-urlencoded content type is a common encoding used by many modern APIs. The FormUrlEncoded body builds this content by serializing key-value pairs defined by various FormParam elements.

Here is an example of FormUrlEncoded:

Multipart

Multipart bodies allow for combining String and File attachment content. This is a useful tool for uploading data to web services. This element has two child element types: StringPart and FilePart. Any number of these elements can be used when building the Multipart message.

StringPart is relatively simple: just provide a name for the part, and a String value for the part, in the form of attributes on this element.

FilePart has a number of attributes for the various configurations it needs. Like StringPart, it must have a name assigned to it. It also needs a filename for the file being uploaded, and an absolute filepath to that file. Lastly, the contentType of that file must be specified.

Lastly, an optional custom boundary can be added through the boundary attribute on the Multipart element.

Here is an example of Multipart:

  • 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:

  • Execution Scope

Like the Execution element, the Response element functions as an Execution Scope. This means that it can have child elements that are any of the HTTP Method element, general workflow elements, utility elements, etc. Nearly every execution-related element in the API XL schema can be used as a child of the Response element, allowing for complex actions to be performed with the Response.

It should be noted that nesting additional requests inside of Response elements, again and again, can lead to an API XL structure that can be a bit more difficult to follow due to all the nested levels of operation. It is recommended that in most cases, the response content should be set as a variable so it can be retrieved outside of the Response element’s scope, thus eliminating the need for nesting.

Setting variables are covered in more detail in the sections on Variables and the General Workflow section.

  • Response Attributes

The Response element has a series of attributes that are defined on it that affect how the Response is handled. These attributes are powerful tools that have a significant impact on what actions are taken afterwards.

“as”: the name of the variable that the response should be stored in. Setting this variable automatically stores the response in a variable with that name, which can be accessed by Dynamic Expressions. The expression uses the value of the “as” attribute as the name to retrieve the response data.

“encoding”: the format of the response body when it arrives. This is necessary so that the response content can be exposed in the proper format via the variable defined in the “as” attribute. Setting this properly requires knowing what kind of format is returned by the HTTP Response. There is a specific range of encoding types supported by API XL, all of which are visible using the API XL Format Builder in the PilotFish Data Mapper.

“formatAs”: instruction API XL to automatically convert the format of the response content befor estoring it in the variable named in the “as” attribute. This is a very useful mechanism for converting a format that might not be as easily parse-able within API XL into a format that is more parse-able. The most common use of this is converting a format like JSON into XML so that XPath expressions can be used on it. There is a specific range of formatting types supported by API XL, all of which are visible using the API XL Format Builder in the PilotFish Data Mapper.

“status”: the status code from the response as a variable. This attribute sets the name of that variable that the status code value will be stored within. It is a temporary variable, and only exists within the scope of the Response element.

  • General Workflow

There are a wide range of elements in API XL that can be considered General Workflow types of components. These provide support for things like variable management, flow-control, exception handling, output, etc. Using these elements allows for providing instructions that allow for a much more sophisticated flow to the HTTP web calls.

  • 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:

  • Building The Output Document

Every Output element evaluates to create a single new XML element in the output document, with a specific name specified in the “name” attribute. They can also be nested to create an element hierarchy. This allows Output elements to be used to build completely custom document structures based on what the user desires.

Here is an example of a collection of Output elements building the structure of a document:

And here is the actual XML output that would create. Notice how elements were created to match the structure of the Output elements:

  • Passing in Values

Output elements accept values via the “value” attribute. This attribute accepts anything from arbitrary text content to variable values.

Here is the Output example from before, with values provided:

This example would populate those values (after evaluating the OGNL expressions) into this output document:

  • Formatting Output

By default, anything passed into the “value” attribute is formatted as a String and passed in as text content to the XML output document. However, there are times when the value should not be treated as a String. The most common example of which is XML content, which would be outputted as escaped XML if formatted as a String.

This is resolved via the “formatAs” attribute. This specifies an automatic conversion from one format to another. Here is the example from earlier, using “formatAs”:

And here is that output, with that value formatted as XML:

  • Manually Adding XML

There is also the option of manually adding XML as children of an Output tag. This prevents that Output tag from functioning as an Execution Scope, and also is limited in support for Dynamic Expressions. However, it is a feature that is provided.

Essentially, any XML outside of the API XL namespace will simply be written to the Output. 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 as 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:

  • Utility

Utility elements help with handling things like debugging and error handling in API XL.

  • 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:

  • Try

The Try element is an Execution Scope, which means that any Execution-related elements can be placed within it. However, any exceptions thrown from within this element will not automatically cause the API XL execution to fail. If a Catch element exists within the parent TryCatch element, the exception will be handled there.

  • Catch

The Catch element exists to handle exceptions thrown from within the Try element. Catch is an Execution Scope, meaning any Execution-related elements can be placed within it, including HTTP method calls. Any exceptions thrown from within Catch will propagate out normally.

Catch has a single attribute, “as”. This attribute is used to set a name for the temporary variable that the Java Exception object can be exposed as. This allows the Exception to be handled by the child elements of Catch.

  • Finally

The Finally element will always execute within the TryCatch block, even if an exception occurs in either the Try or Catch elements. Finally executes after the Try and (if it exists) Catch elements have finished executing.

Finally is an Execution Scope, meaning any Execution-related elements can be placed within it, including HTTP method calls.

  • Response Object API

One of the options for handling an HTTP Response is to use the “response” encoding. This means the entire response will be stored in a special class called ResponseType. This class is a container that holds the response body content, status code, and all headers. This should only be used if additional information beyond just the response body is needed.

As a Java object, the ResponseType instance can be accessed using OGNL expressions to invoke its methods, using a very simple API for retrieving its values:

  • 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 OGNL expression using this method is:

ognl:#responseVariable.getContents()

  • Supported Encodings

While all encodings for data passed via HTTP web calls are ultimately supported, there are several broad types that tell API XL how to handle the data. These types are also used for implicit conversion via elements that support the “formatAs” attribute.

One of these encodings must be provided anywhere that an “encoding” or “formatAs” attribute is specified.

“string”: this just treats the data as a String with the default system encoding.

“stream”: this is a simple binary stream, or blob. It can contain anything within it.

“cache”: this is a PilotFish Cache object, which provides a flexible and dynamic way of handling binary content.

“xml”: this is XML content, either an XML String or a DOM construct.

“base64”: this is for Base64 encoded content.

“json”: this is JSON content, either a JSON String or some object representation.

“response”: this is a special type that only applies to the Response element. It is for using the ResponeType class for storing the HTTP response.

This is a unique website which will require a more modern browser to work! Please upgrade today!

Thanks!

Our editors are notified.

Close