Interface Mapper

Special considerations for interface fields of JSON (RESTful) service interfaces

Path and Query fields

Interface Fields have three location options: Body, Path, or Query. Body means that the interface field corresponds to the body of the JSON message. Path and Query are for fields which correspond to the request URI used to invoke the operation. For Path fields, you specify the corresponding part of the URI by going to Operation > Properties and selecting the Path/HTTP tab. Query interface fields correspond to the query string at the end of a request URI. A Path or Query interface field must have a primitive data type, though it may have a nonzero Occurs value (which would be expressed in the actual URI as a comma-separated array). Note that a Path or Query interface field need not have a mapping if it is intended to only be used for output filtering, as described below.

At run time, the output response body is filtered by any path- and query-parameter values received in the URI whose parameter names match the name of an output field in the response body. For example, if an operation is defined with a path of /cars/{make} and an output body array of "car" items, and the run-time request URI is .../cars/ford?color=red&doors=4 (where "make", "color" and "doors" are all names of fields defined within "car"), then the response body array would exclude any instances of "car" whose "make", "color", and "doors" values don't match the URI-specified values. If there are two or more body fields with the same name, those fields can be differentiated in the query string by specifying one or more parent fields of the desired field separated with periods (e.g. car.color=red). Partial or incomplete values for filtering can be indicated by using an asterisk character (*) at the beginning and/or end of the value (e.g. color=red* would match both "red" and "reddish"). Case-sensitive filtering can be performed by wrapping the value in single quotes (e.g. color='Red'). Note that if you do not want a Path or Query interface field to act as a filter on the output message, ensure that its name does not match the name of any output Body interface field. Additionally, there are four special built-in query parameters that can provide further control over the contents of the response:

$fields=commaSeparatedListOfOutputFieldNames>

Indicates that the response body is to contain only the specified fields (and their parent fields and any subordinate fields) and exclude all other defined fields of the response.

$limit=maxNumberOfItems

For array paging, specifies the maximum total number of array elements to return in the response.

$offset=startIndex

For array paging, specifies the minimum index of any returned array elements in the response.

$sort=commaSeparatedListOfOutputFieldNames

For array sorting, indicates that any returned array elements in the response are to be sorted by the specified field(s), by default in ascending order. Optionally, placing a plus (+) or minus (-) character before a field name indicates the order is to be ascending or descending, respectively.

Anonymous root field

For service interface operations that send and/or receive a JSON message body, even though the outermost (root) structure, i.e. a JSON object, array, or primitive, is obligatorily nameless in the message, it still must be represented in the operation's interface fields as the top-level Body field (so that it can be given a Type and Occurs). This so-called "anonymous root" interface field will be marked with an asterisk (*) to the right of the Location column and, though it will have a name in the Interface Mapper, that name will not appear in the JSON message. Since there cannot be more than one input top-level Body interface field nor more than one output top-level Body interface field in an operation, all interface fields that appear in the body of a message must be children of the top-level Body field. See picture below showing an example of a message body with an a nonymous-root group field in the Interface Mapper and its corresponding {}-enclosed JSON object in the JSON message.

Array fields in JSON

In SOAP (like COBOL), an array is an item defined with a nonzero occurs attribute, and such an item appears in the message repeated multiple times. For example, an interface-field group array named "group1", with occurs 2, would be represented in a SOAP message as follows:

<group1>
  <field1>someValue1</field1>
  <field2>someValue2</field2>
</ group1>
< group1>
  <field1>someValue3</field1>
  <field2>someValue4</field2>
</ group1>

JSON is different in that it provides explicit array syntax such that an array item is not a repeated item but rather a single item that contains repeated values. So, the same interface-field group array from above would look like the following in a JSON message. Note how "group1" is not repeated but rather appears only once and contains the individual array-element values, which appear as repeated {}-enclosed JSON objects.

"group1":
[
  {
   "field1":"someValue1",
   "field2":"someValue2"
  },
  {
   "field1":"someValue3",
   "field2":"someValue4"
  }
]

For "group1" to be included in each repeated array element value in the JSON message (so that it would look more like the SOAP message), an extra interface-field group would be needed as a parent of the "group1" field in the Interface Mapper, and the nonzero occurs put on that extra parent field instead of on "group1". The resulting JSON message would then be as follows:

"extraGroup":
[
  {
    "group1":
    {
      "field1":"someValue1",
      "field2":"someValue2"
    }
  },
  {
    "group1":
    {
      "field1":"someValue3",
      "field2":"someValue4"
    }
  }
]

For all service interfaces in general, a nonzero occurs property indicates that an interface field is an array. However, for JSON service interfaces in particular, when an interface field has specifically occurs 1, it will appear in the JSON message as a single object or primitive, without the JSON array syntax.