05_Mapping your API Response Formats

Last updated
Save as PDF

API Response Formats

CMO can parse API Response if it is in one of 2 supported formats: JSON or XML. There is no schema restrictions for data returned by external API at initial parsing stage. But when API Response is mapped to specific responses schema must be as specified in Response Mapping.

Click here for Example Code for each format type.

Single Record Return

API Response is considered a single data record. Pieces of API Response can be mapped to Responses of simple type. Once API Call performed CMO extracts data from API Response and replaces values in the mapped responses. An Event Response can be mapped to only one field from API Response.

List of supported event response types:

Text - Single Line
Text - Multiple Line
Number
Score
Date
Time (format: 24 hour "HH:mm", e.g. "19:49")
Capture GPS (format "longitude latitude", e.g. "52.5230361 13.4012308")
Drop Down
Drop Down Improved
Drop Down Editable
Items / Sub Items
Multi Level Drop Down

For JSON Response format: API can return a single JSON object (nested objects are also supported) or single plain JSON value. Extracting data from JSON arrays is not supported for this Type-of-Return. In order to map an Event Response to a field of JSON API Response - JSON Object Field path should be provided.

Consider the following API Response:

{
    "loginName": "john.doe",
    "firstName": "John",
    "lastName": "Doe",
    "age": 45,
    "joined": "2005-06-29",
    "lastSeen": {
        "time": "18:15",
        "location": "21.351316 -157.923754"
    }
}

Field path firstName refers to field with "firstName" name in the root JSON object.

Field path lastSeen.time refers to field with "time" name in nested "lastSeen" JSON object, which is placed in the root JSON object.

Field path "" (empty string) refers to the root JSON value itself. This is useful for the case when API return plain JSON value (string, number, bool... but not object or array).

For XML Response format: API can be any XML. In order to map an Event Response to a field of XML API Response - XPath expression should be provided. The first value found by XPath expression is used.

Consider the following API Response:

<Employee loginname="john.doe">
    <PersonalDetails>
        <FirstName>John</FirstName>
        <LastName>Doe</LastName>
        <Age>45</Age>
    </PersonalDetails>
    <Joined on="2005-06-29" />
    <Audit>
        <LastSeen time="18:15">
            <GPSLocation>21.351316 -157.923754</GPSLocation>
        </LastSeen>
    </Audit>
</Employee>

XPath /Employee/@loginname will refer to "loginname" attribute value of root "Employee" node.

XPath //FirstName/text() will refer to text content of the first "FirstName" node placed anywhere in the XML.

Multiple Record Return - Store Single Record

API Response is considered a set of data records. After initial parsing of API response CMO looks for array of records, and then extracts data from each record. If API returns array of more than 1 record - a pop-up with record list is presented to the user with prompt to select one record. When record is selected in the pop-up - it is processed so values of mapped responses are replaced with data of the selected record. If API returns only one record - the select record pop-up is not shown to the user and the received record is processed automatically as it was selected by the user. Pieces of selected data record can be mapped to Responses of simple type.

List of supported response types:

Text - Single Line
Text - Multiple Line
Number
Score
Date
Time (format: 24 hour "HH:mm", e.g. "19:49")
Capture GPS (format "longitude latitude", e.g. "52.5230361 13.4012308")
Drop Down
Drop Down Improved
Drop Down Editable
Items / Sub Items
Multi Level Drop Down

For JSON Response format:

API can return JSON array itself, or array can be part of another JSON object. In order to find array with records within JSON API Response a JSON Array Field path should be provided.

Consider the following API Response:

{
    "loginName": "john.doe",
    "firstName": "John",
    "lastName": "Doe",
    "age": 45,
    "joined": "2005-06-29",
    "lastSeen": {
        "time": "18:15",
        "location": "21.351316 -157.923754"
    }
}

Array Field path employees refers to array under "employees" field in the root JSON object.

Array Field path holidays.national refers to array in "national" field in nested "holidays" JSON object, which is placed in the root JSON object.

Array Field path "" (empty string) refers to the root JSON Array. This is useful for the case when API return unwrapped JSON Array, for example:


    {"firstName": "John", "lastName": "Doe"},
    {"firstName": "Jane", "lastName": "Doe"}
]

In order to map an Event Response to a field of Record - Array Item Field path should be provided. Array Item Field path refers field relative to Array Item object.

Consider the following API Response:

{
    "employees": [
        {"firstName": "John", "lastName": "Doe", "lastSeen": {"time": "18:15"}},
        {"firstName": "Jane", "lastName": "Doe", "lastSeen": {"time": "05:35"}}
    ]
}

If JSON Array Field path is "employees"

Array Item Field path firstName will refer to firstName field in objects that are employee array items.
Array Item Field path lastSeen.time will refer to "time" field of lastSeen nested objects.
Array Item Field path "" (empty string) will refer array item JSON value itself. It is useful for the cases when array contains plain JSON values (not JSON objects).

For XML Response format:

Array is extracted from received XML by XPath expression.

For example consider the following XML API Response:

<Employees>
    <Employee loginname="john.doe">
        <PersonalDetails>
            <FirstName>John</FirstName>
            <LastName>Doe</LastName>
            <Age>45</Age>
        </PersonalDetails>
        <Joined on="2005-06-29" />
        <Audit>
            <LastSeen time="18:15">
                <GPSLocation>21.351316 -157.923754</GPSLocation>
            </LastSeen>
        </Audit>
    </Employee>
    <Employee loginname="jane.doe">
        <PersonalDetails>
            <FirstName>Jane</FirstName>
            <LastName>Doe</LastName>
            <Age>23</Age>
        </PersonalDetails>
        <Joined on="2018-09-15" />
        <Audit>
            <LastSeen time="04:59">
                <GPSLocation>52.5230361 13.4012308</GPSLocation>
            </LastSeen>
        </Audit>
    </Employee>
</Employees>

Array XPath /Employees/Employee will refer to all "Employee" nodes with in "Employees" node.

Array XPath //FirstName/text() will refer to all text content strings of all "FirstName" nodes.

In order to map an Event Response to a field of Record - XPath relative to Array Item should be provided.

XPath ./PersonalDetails/FirstName/text() refers to the text content of FirstName node placed in PersonalDetails node in each Employee node.

XPath .//Joined/@on refers to "on" attribute value of Joined node in each Employee node.

XPath "" (empty string) refers to array item itself. Useful for the case when Array XPath enumerates text content or some attribute value of some nodes.

Multiple Record Return - Store Table

API Response is considered a set of data records. After initial parsing of API response CMO looks for array of records, and then it extracts data for each record. Extracted data records can be stored in Table Response.

Table Response shows table on Perform Event screen. Table Columns are configured in form builder. Each column has Field Name and Header Text. Field Name is used for mapping data from API Response to table columns.

JSON Array Field path, JSON Array Item path, Array XPath and XPath (relative to Array Item) work the same way as for "Multiple Record Return - Store Single Record" type-of-return.

Example Code Formats

Example of API with JSON Response that returns single-record-response


{
    "loginName": "john.doe",
    "firstName": "John",
    "lastName": "Doe",
    "age": 45,
    "joined": "2005-06-29",
    "lastSeen": {
        "time": "18:15",
        "location": "21.351316 -157.923754"
    }
}

Example of API with JSON Response that returns multiple-record-response

{
    "employees": [{
        "loginName": "john.doe",
        "firstName": "John",
        "lastName": "Doe",
        "age": 45,
        "joined": "2005-06-29",
        "lastSeen": {
            "time": "18:15",
            "location": "21.351316 -157.923754"
        }
    }, {
        "loginName": "jane.doe",
        "firstName": "Jane",
        "lastName": "Doe",
        "age": 23,
        "joined": "2018-09-15",
        "lastSeen": {
            "time": "04:59",
            "location": "52.5230361 13.4012308"
        }
    }]
}

Example of API with XML Response that returns single-record-response

<Employee loginname="john.doe">
    <PersonalDetails>
        <FirstName>John</FirstName>
        <LastName>Doe</LastName>
        <Age>45</Age>
    </PersonalDetails>
    <Joined on="2005-06-29" />
    <Audit>
        <LastSeen time="18:15">
            <GPSLocation>21.351316 -157.923754</GPSLocation>
        </LastSeen>
    </Audit>
</Employee>

Example of API with XML Response that returns multiple-record-response


<Employees>
    <Employee loginname="john.doe">
        <PersonalDetails>
            <FirstName>John</FirstName>
            <LastName>Doe</LastName>
            <Age>45</Age>
        </PersonalDetails>
        <Joined on="2005-06-29" />
        <Audit>
            <LastSeen time="18:15">
                <GPSLocation>21.351316 -157.923754</GPSLocation>
            </LastSeen>
        </Audit>
    </Employee>
    <Employee loginname="jane.doe">
        <PersonalDetails>
            <FirstName>Jane</FirstName>
            <LastName>Doe</LastName>
            <Age>23</Age>
        </PersonalDetails>
        <Joined on="2018-09-15" />
        <Audit>
            <LastSeen time="04:59">
                <GPSLocation>52.5230361 13.4012308</GPSLocation>
            </LastSeen>
        </Audit>
    </Employee>
</Employees>