REST Adapter Capabilities

The REST Adapter can expose integrations as REST APIs by configuring a REST Adapter connection as a trigger. The REST Adapter can also consume any external REST API by configuring a REST Adapter connection as an invoke. This section identifies the capabilities of the REST Adapter when used as a trigger or invoke connection.

Note:

The REST Adapter treats all endpoints as they are exposed. The REST Adapter does not filter or change any of the APIs exposed by the application to which you are connecting. If there is a native adapter for the application to which you are connecting, use that adapter instead. If you choose to use the REST Adapter instead of the native adapter, the API restrictions and deprecation policies apply as specified in the respective application’s documentation.

To connect to the Oracle HCM Cloud SOAP APIs, see Oracle HCM Cloud Adapter Capabilities.

The REST Adapter provides the following capabilities when exposing an integration as a REST API by configuring the connection as a trigger:

  • Support for uploading sample JSON documents to define schema during REST Adapter configuration.

  • REST APIs implement the HTTPS protocol, thereby enforcing all incoming requests to have transport level security.

  • REST APIs exposed using the REST Adapter are protected using Basic Authentication and OAuth token-based authentication.

  • Supports configuration of the following:

    • Relative resource URI.

    • Support for HTTP methods GET, PUT, POST, DELETE, and PATCH.

    • Template and query parameters.

    • Support for a request/response payload.

    See Configuration Parameters.

  • Support for standard and custom HTTP headers to model an integration to expose standard and custom HTTP header properties to Oracle Integration Cloud Service for downstream processing (see Standard and Custom Header Support).

  • Support for multipart attachments (content-types: multipart/mixed and multipart/form-data) in request/response messages while creating an integration to expose a REST endpoint that accepts incoming request messages with multipart attachments and/or sends responses with multipart attachments (see Multipart Attachment Support for Trigger and Invoke Connections).

  • REST APIs exposed using the REST Adapter can be configured to be CORS-compliant (see Cross-Origin Resource Sharing (CORS)).

  • Support for exposing a REST endpoint that can accept the request and process it asynchronously.

  • A Swagger 2.0–compliant document is automatically produced for REST APIs exposed using the REST Adapter. This document describes the metadata for the generated REST APIs (see Viewing the Metadata for the Inbound REST Endpoint in Swagger Format).

The REST Adapter provides the following capabilities when consuming external REST APIs by configuring the connection as an invoke:

  • Support for uploading sample XML documents to define schema for XML content during REST Adapter configuration. The following XML documents are supported for schema generation:
    • XML with no namespace

    • XML with a homogenous namespace

    • XML files up to 3 MB in size

  • Support for uploading sample JSON documents to define schema during REST Adapter configuration.

  • Support for consuming any REST API described using Swagger 2.0/RAML documents and the Oracle Metadata Catalog. The REST Adapter can automatically discover and present the available resources and operations present in the documents for configurations. The metadata regarding operation-specific request and response messages available in the document is automatically made available for mapping and other activities. (see Swagger and RAML Document Support for Describing External REST APIs).

  • Supports configuration of the following (see Configuration Parameters).

    • Relative resource URI.

    • Support for HTTP methods GET, PUT, POST, DELETE, and PATCH.

    • Template and query parameters.

    • Support for a request/response payload:

    Note:

    The REST Adapter automatically encodes the value of query parameters before invoking a service. The REST Adapter has no way of knowing if you have already encoded a query parameter. Ensure that you assign unencoded values to query parameters. Assigning encoded values leads to double encoding.

    For example, assume query parameter q has the following value:

    q=a+b

    This may mean that the value of q was intended to be a b, but was encoded by the user.

    The intention may also have been to send a+b, which must be URL-encoded as a%2Bb before sending.

  • Support for accessing and setting standard and custom HTTP headers exposed by external REST APIs (see Standard and Custom Header Support).

  • Support for multipart attachments (content-type: multipart/mixed, multipart/form-data ) in request/response messages in an integration flow while sending a request to an external REST endpoint that accepts incoming request messages with multipart attachments and/or sends responses with multipart attachments (see Multipart Attachment Support for Trigger and Invoke Connections).

  • Support for consuming external REST APIs that are not described using Swagger /RAML documents. You can declaratively specify the HTTP method and the sample JSON document/XML schema for describing the shape of the request and response messages.

  • Support for consuming external REST APIs that are protected using transport level security.

  • Support for consuming REST APIs protected using HTTP Basic Authentication, OAuth Client Credentials (two-legged flow), OAuth Resource Owner Password Credentials (two-legged flow), OAuth Authorization Code Credentials (three-legged flow), OAuth Custom Three Legged Flow, and OAuth Custom Two Legged Flow. There is also support for consuming APIs that are unprotected.

  • Extensibility support to access plurality of OAuth 2 providers (see Extensibility Support for Multiple OAuth Providers).

  • Consumption of on-premises REST APIs residing behind the fire wall using the connectivity agent (see On-Premises REST API Support with the Agent).

  • Support for dynamically changing the (invoke) outbound endpoint configuration (see Support for Dynamic REST Endpoints).

Note:

XML documents passed to a REST endpoint that support the application/XML content type must comply with the XML schema specified during trigger (inbound) REST configuration. When the REST invokes a target endpoint, the application/XML response must comply with the XML schema specified during invoke (outbound) REST response configuration.

The following sections describe these capabilities in more detail:

Configuration Parameters

You configure the following parameters using the Endpoint Configuration Wizard to expose and consume a REST service.
  • Relative resource path URI

  • HTTP method (actions) to perform

  • Template and query parameters

  • Request/response message structure

Standard and Custom Header Support

The REST Adapter supports standard and custom HTTP request and response headers in the invoke and trigger directions.

  • Outbound (Invoke) direction

    HTTP headers enable you to use an outbound invocation to specify header properties. Many REST APIs expect certain properties to be specified in the HTTP headers (similar to SOAP APIs where you can specify header properties such as the WS address). Use the standard HTTP headers to specify these properties. You can also use the custom HTTP headers to specify properties. The REST APIs can expect the client application to pass properties in the custom headers, which can influence the behavior of the APIs. The standard and custom HTTP header properties configured in the wizard automatically start appearing in the mapper and the Expression Builder. You can map the header properties in the mapper.

  • Inbound (trigger) direction

    You can expose integration flows as REST endpoints and enable client applications to populate the properties in the standard and custom headers. You can use these properties to create routing expressions in your integrations. The standard and custom HTTP header properties configured in the wizard automatically start appearing in the mapper and the Expression Builder. You can map the header properties in the mapper. See Creating Routing Paths for Two Different Invoke Endpoints in Integrations and Creating an Orchestrated Integration.

Note:

  • If you want to send multiple values of a header, use comma separated values (CSVs). This is considered as one header and one value that consists of:

    val1 comma val2 comma val3 ...

    The same value is propagated across the mapper and then to the outbound service. The outbound service must then interpret the CSVs of the header to be used as multiple values.

  • You cannot store multiple headers with the same name. The WSDL can only store one element with one unique name.

Authentication Types

The REST Adapter supports the invocation of external REST endpoints supporting the following types of authentication:
  • Basic Authentication

  • OAuth Client Credentials (two-legged flow)

  • OAuth Resource Owner Password Credentials (two-legged flow)

  • OAuth Authorization Code Credentials (three-legged flow)

  • OAuth Custom Three Legged Flow

  • OAuth Custom Two Legged Flow

  • OAuth 1.0a One Legged Authentication

See Configuring Connection Security for more information about these security policies.

Extensibility Support for Multiple OAuth Providers

You can use the extensibility framework of the REST Adapter to access the OAuth-protected resource of endpoints. This framework enables you to access endpoints that have implemented their own variations of OAuth.

The OAuth standard provides flexibility for endpoints to define specific aspects of their OAuth flows. For example:
  • Create their own properties.

  • Decide when to use these properties in an OAuth flow. For example, some custom properties may be required with the authorization request, while others may be required for the access token request or for the refresh of the access token after its expiration.

  • Decide how to pass these properties in an OAuth flow. For example, whether a property is passed as a header, query parameter, or payload.

To address these challenges, Oracle Integration Cloud Service provides two custom security policies that enable you to specify each step in the OAuth flow when you create the REST Adapter connection:
  • OAuth custom two-legged flow: The client application directly interacts with the authorization server on behalf of a resource owner.

  • OAuth custom three-legged flow: The client application redirects the owner to a separate resource URL where the resource owner authenticates and provides consent for the flow to continue.

This enables you to adapt to most OAuth framework scenarios and integrate with many third-party applications without writing additional code.

  • During design-time, the access token is obtained, validated, and stored in the CSF. The security token is also stored in the CSF.

  • During runtime, the access token is retrieved, applied, and managed. A valid access token is applied to the request before invoking the REST endpoint.

For information about specifying the OAuth custom two-legged flow and three-legged flow security policies, see Configuring Connection Security and How to Implement Specific REST Adapter Features.

Note:

This extensibility feature is an advanced feature, and not for business users. Users of this feature should use a tool such as postman to configure the necessary properties.

Role-Based Connections

The REST Adapter is bidirectional. You can configure the REST Adapter depending on the context in which you want to use the connection.

  • Trigger: The REST Adapter is used to create a REST endpoint to trigger an integration. You select Trigger from the Role list on the Create New Connection dialog. When configured as a trigger, a base URI is not required. The security policy defined in the inbound direction accepts credentials configured in the identity domain. Therefore, you are not required to provide the applicable credentials. When configuring security on the Connections page, you only provide the security policy that must be attached to the inbound endpoint. Basic authentication is the only security policy available. Agent configuration is not applicable on a connection with the trigger role.

  • Invoke: The REST Adapter is used to invoke external REST endpoints. A base URI and security configuration for accessing external protected resources are required. You are prompted for these additional details on the Connections page. You cannot use an invoke connection on the trigger side.

  • Trigger and invoke: The REST Adapter is used in both the trigger and invoke directions of an integration. This connection requires invoke and trigger values.

Cross-Origin Resource Sharing (CORS)

CORS defines a way in which a browser and server can interact to determine safely whether or not to allow the cross-origin request. CORS provides for more flexibility than same-origin requests, but is more secure than simply permitting all cross-origin requests.

Oracle Integration Cloud Service supports CORS in the inbound direction.

CORS is supported by browsers based on the following layout engines:
  • Blink- and Chromium-based browsers (Chrome 28, Opera 15, Amazon Silk, Android's 4.4+ WebView, and Qt's WebEngine).

  • Gecko 1.9.1 (Firefox 3.5, SeaMonkey 2.0, and Camino 2.1) and above.

  • MSHTML/Trident 6.0 (Internet Explorer 10) has native support. MSHTML/Trident 4.0 & 5.0 (Internet Explorer 8 & 9) provide partial support through the XDomainRequest object.

  • Presto-based browsers (Opera) implement CORS as of Opera 12.00 and Opera Mobile 12, but not Opera Mini.

  • WebKit (Safari 4 and above, Google Chrome 3 and above, possibly earlier).

The following browsers do not support CORS:
  • Camino does not implement CORS in the 2.0.x release series because these versions are based on Gecko 1.9.0

  • As of version 0.10.2, Arora exposes WebKit's CORS-related APIs, but attempted cross-origin requests fail.[16]

For CORS to work, you must send an OPTIONS request. Using the XMLHttpRequest object in Javascript for (Ajax calls) automatically sends the OPTIONS request. If XMLHttpRequest is not used, then the OPTIONS request must be sent explicitly.

In the following example, an HTML client invokes an Oracle Integration Cloud Service CORS-based endpoint using XMLHttpRequest.
<html>

<script language="javascript">

var invocation = new XMLHttpRequest(); 
var url =
"<ics endpoint url>";
// Use postman to generate authCode. Sample is provided below 
var authCode = 'Basic <base64encoded authorization string>';  

function callOtherDomain(){   if(invocation)     {       
invocation.open('GET', url, true);       
invocation.setRequestHeader('Accept', 'application/json'); 
invocation.setRequestHeader('X-Cache','aaa');   
invocation.setRequestHeader('X-Forwarded-For','fwd1'); 
invocation.setRequestHeader('Authorization',authCode); 
invocation.onreadystatechange = stateChangeEventHandler; 
invocation.send(); 
} 
} 

function stateChangeEventHandler() 
{ 
//  check whether the data is loaded 
if (invocation.readyState==4)  
 {  // check whether the status is ok   
  if (invocation.status==200)   {   
  //alert(invocation.responseText) 
document.getElementById("myTextarea").value = invocation.responseText 
document.write("hello"); 
document.write(invocation.responseText);   
  }  
  else  
  {  
    alert ("Error Occurred")  
  }   
   } 
}

</script>
<body onload="callOtherDomain()">
<br><br>
<textarea id="myTextarea" name="mytextarea1"></textarea><br><br>
</body>
</html>
Some browsers may also have security restrictions such as the same origin policy or a similar name that prevents using CORS. For example, to access a CORS-enabled endpoint using a Chrome browser, you may have to start it with web security disabled as follows.
chrome.exe --user-data-dir="C:/Chrome dev session" --disable-web-security

Swagger and RAML Document Support for Describing External REST APIs

The REST Adapter provides support for consuming REST APIs that are described in either a Swagger or RAML document

  • RESTful API Modeling Language (RAML): A language for describing RESTful APIs. RAML provides the information necessary to describe RESTful or practically-RESTful APIs (APIs that do not obey all REST constraints).

  • Swagger: A specification for describing, producing, consuming, and visualizing RESTful web services.

The following example shows a Swagger 2.0 file. This file contains two main resources:
  • /Book. This resource contains get and post methods and /Book/{id}, /Book/hello, and /Book/search subresources.

  • /Author. This resource contains a get method and an /Author/{id} subresource.

When configuring an invoke (outbound) REST Adapter in the Endpoint Configuration Wizard, the resources and subresources are displayed for selection as business objects and the methods are displayed for selection as operations to perform on the business objects.

When creating the REST Adapter connection, you select Swagger Definition URL in the Connection Type field and specify the URL in the Connection URL field of the Connection Properties dialog.

{

  "swagger" : "2.0",
  "info" : {
    "version" : "1.0",
    "title" : "RestServiceForBooks"
  },

  "host" : "host_name:8080",
  "basePath" : "/Test/rest",
  "schemes" : ["http"],
  "paths" : {
    "/Book" : {
      "get" : {
        "operationId" : "getBooks",
        "description" : "Returns all the available books in teh store",
        "produces" : [ "application/xml", "application/json" ],
        "responses" : {
          "default" : {
            "schema" : {
              "$ref" : "#/definitions/Books"
            }
          }
        }

      },
      "post" : {
        "operationId" : "postBook",
        "description" : "Creates a new book item",
        "produces" : [ "application/xml", "application/json" ],
        "consumes" : [ "application/xml", "application/json" ],
        "parameters" : [
          {
            "name" : "Book",
            "in" : "body",
            "required" : true,
            "schema" : { "$ref" : "#/definitions/Book" }
          }
        ],
        "responses" : {
          "default" : {
            "schema" : { "$ref" : "#/definitions/Book" }
          }
        }
      }
    },
    "/Book/{id}" : {
      "get" : {
        "operationId" : "getSingleBook",
        "description" : "Returns a book with specific id",
        "produces" : [ "application/xml", "application/json" ],
        "parameters" : [
          {
            "name": "id",
            "in": "path",
            "required" : true,
            "type" : "string"
          }
        ],
        "responses" : {
          "default" : {
            "schema" : { "$ref" : "#/definitions/Book" }
          }
        }
      }
    },
    "/Book/hello" : {
      "get" : {
        "operationId" : "sayHelloToBook",
        "description" : "says hello to a book",
        "produces" : [ "application/xml", "application/json" ],
        "responses" : {
          "default" : {
            "schema" : { "type" : "string" }
          }
        }
      }
    },
    "/Book/search" : {
      "get" : {
        "operationId" : "searchBook",
        "description" : "Returns a list of books that match query param",
        "produces" : [ "application/xml", "application/json" ],
        "parameters" : [
          {
            "name": "name",
            "in": "query",
            "required" : false,
            "type" : "string"
          }
        ],
        "responses" : {
          "default" : {
            "schema" : {
              "$ref" : "#/definitions/Books"
            }
          }
        }
      }
    },
    "/Author" : {
      "get" : {
        "operationId" : "getAuthors",
        "description": "Returns a list of authors",
        "produces": [
          "application/xml",
          "application/json"
        ],
        "responses": {
          "default": {
            "schema": {
              "$ref" : "#/definitions/Authors"
            }
          }
        }
      }
    },
    "/Author/{id}" : {
      "get" : {
        "operationId" : "getSingleAuthor",
        "description" : "Returns a Author with specific id",
        "produces" : [ "application/xml", "application/json" ],
        "parameters" : [
          {
            "name": "id",
            "in": "path",
            "required" : true,
            "type" : "string"
          }
        ],
        "responses" : {
          "default" : {
            "schema" : { "$ref" : "#/definitions/Author" }
          }
        }
      }
    }
  },
  "definitions" : {
    "Author" : {
      "type" : "object",
      "properties" : {
        "id" : { "type" : "string" },
        "firstName" : { "type"  : "string"},
        "lastName" : { "type" : "string" }
      },
      "required" : [ "id", "firstName", "lastName"]
    },
    "Authors" : {
      "type" : "object",
      "properties" : {
        "items" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/Author"
          }
        }
      }
    },
    "Publisher" : {
      "type" : "object",
      "properties" : {
        "id" : { "type" : "string" },
        "name" : { "type"  : "string"},
        "location" : { "type" : "string" }
      },
      "required" : [ "id", "name", "location"]
    },
    "Publishers" : {
      "type" : "object",
      "properties" : {
        "items" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/Publisher"
          }
        }
      }
    },
    "Book" : {
      "type" : "object",
      "properties" : {
        "id" : { "type" : "string" },
        "name" : { "type" : "string" },
        "ISBN" : { "type" : "string" },
        "price" : { "type" : "integer" },
        "author" : { "type" : "array", "items" :{ "$ref" : "#/definitions/Author" } },
        "publisher" : { "$ref" : "#/definitions/Publisher"  }
      },
      "required" : ["id", "name", "ISBN", "price", "author", "publisher" ]
    },
    "Books" : {
      "type" : "object",
      "properties" : {
        "items" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/Book"
          }
        }
      }
    }
  }
}

The following example shows a RAML file. The file contains the schemas that use the service. This file contains two main resources:

  • /Author. This resource contains a get method and an /Author/{id} subresource.

  • /Book. This resource contains get and post methods and /Book/{id} and /Book/search subresources.

When configuring an invoke (outbound) REST Adapter in the Endpoint Configuration Wizard, the resources and subresources are displayed for selection as business objects and the methods are displayed for selection as operations to perform on the business objects.

When creating your REST Adapter connection, you select RAML Definition URL in the Connection Type field and specify the URL in the Connection URL field of the Connection Properties dialog.

 #%RAML 0.8
title: API for Books
version: v1
baseUri: "http://host_name:8080/Test/rest"
protocols: [ HTTP ]
schemas: 
 - authors-jsonschema: |
    {  
      "$schema" : "http://json-schema.org/draft-03/schema",         
       "type":"object",
       "properties":{  
          "items":{  
           "type":"array",
           "items":{  
                 "type":"object",
                 "properties":{  
                    "id":{  
                       "type":"string"
                    },
                    "firstName":{  
                       "type":"string"
                    },
                    "lastName":{  
                       "type":"string"
                    }
                 },
                 "required":[  
                    "id",
                    "firstName",
                    "lastName"
                 ]                
             }
          }
       }
    }
 - author-jsonschema: |
    {  
       "$schema":"http://json-schema.org/draft-03/schema",

             "type":"object",
             "properties":{  
                "id":{  
                   "type":"string"
                },
                "firstName":{  
                   "type":"string"
                },
                "lastName":{  
                   "type":"string"
                }
             },
             "required":[  
                "id",
                "firstName",
                "lastName"
             ]
    }

 - books-jsonschema: |
    {  
       "$schema":"http://json-schema.org/draft-03/schema",

             "type":"object",
             "properties":{  
                "items":{  
                   "type":"array",
                   "items":{                        
                         "type":"object",
                         "properties":{  
                            "id":{  
                               "type":"string"
                            },
                            "name":{  
                               "type":"string"
                            },
                            "ISBN":{  
                               "type":"string"
                            },
                            "price":{  
                               "type":"integer"
                            },
                            "author":{  
                               "type":"array",
                               "items":{  
                                  "type":"object",
                                  "properties":{  
                                     "id":{  
                                        "type":"string"
                                     },
                                     "firstName":{  
                                        "type":"string"
                                     },
                                     "lastName":{  
                                        "type":"string"
                                     }
                                  },
                                  "required":[  
                                     "id",
                                     "firstName",
                                     "lastName"
                                  ]
                               }
                            },
                            "publisher":{  
                               "type":"object",
                               "properties":{  
                                  "id":{  
                                     "type":"string"
                                  },
                                  "name":{  
                                     "type":"string"
                                  },
                                  "location":{  
                                     "type":"string"
                                  }
                               },
                               "required":[  
                                  "id",
                                  "name",
                                  "location"
                               ]
                            }
                         },
                         "required":[  
                            "id",
                            "name",
                            "ISBN",
                            "price",
                            "author",
                            "publisher"
                         ]                      
                   }
                }
             }

    }
 - book-jsonschema: |
    {  
       "$schema":"http://json-schema.org/draft-03/schema", 
             "type":"object",
             "properties":{  
                "id":{  
                   "type":"string"
                },
                "name":{  
                   "type":"string"
                },
                "ISBN":{  
                   "type":"string"
                },
                "price":{  
                   "type":"integer"
                },
                "author":{  
                   "type":"array",
                   "items":{  
                      "type":"object",
                      "properties":{  
                         "id":{  
                            "type":"string"
                         },
                         "firstName":{  
                            "type":"string"
                         },
                         "lastName":{  
                            "type":"string"
                         }
                      },
                      "required":[  
                         "id",
                         "firstName",
                         "lastName"
                      ]
                   }
                },
                "publisher":{  
                   "type":"object",
                   "properties":{  
                      "id":{  
                         "type":"string"
                      },
                      "name":{  
                         "type":"string"
                      },
                      "location":{  
                         "type":"string"
                      }
                   },
                   "required":[  
                      "id",
                      "name",
                      "location"
                   ]
                }
             },
             "required":[  
                "id",
                "name",
                "ISBN",
                "price",
                "author",
                "publisher"
             ]
    }
/Author:
  get: 
    responses: 
      200: 
        body: 
          application/xml: 
            schema: authors-jsonschema
            example: |
              <?xml version="1.0" encoding="UTF-8"?>
              <authors></authors>
          application/json: 
            schema: authors-jsonschema
            example: |
              {
                "authors" : ""
              }
  /{id}: 
    get: 
      responses: 
        200: 
          body: 
            application/xml: 
              schema: author-jsonschema
              example: |
                <?xml version="1.0" encoding="UTF-8"?>
                <author></author>
            application/json: 
              schema: author-jsonschema
              example: |
                {
                  "author" : ""
                }
/Book: 
  post: 
    body: 
      application/xml: 
        schema: book-jsonschema
      application/json: 
        schema: book-jsonschema
    responses: 
      200: 
        body: 
          application/xml: 
            schema: book-jsonschema
            example: |
              <?xml version="1.0" encoding="UTF-8"?>
              <book>
                <price></price>
              </book>
          application/json: 
            schema: book-jsonschema
            example: |
              {
                "book" : {
                  "price" : ""
                }
              }
  get: 
    responses: 
      200: 
        body: 
          application/xml: 
            schema: books-jsonschema
            example: |
              <?xml version="1.0" encoding="UTF-8"?>
              <book>
                <price></price>
              </book>
          application/json: 
            schema: books-jsonschema
            example: |
              {
                "book" : {
                  "price" : ""
                }
              }
  /search: 
    get: 
      queryParameters: 
        name: 
      responses: 
        200: 
          body: 
            application/xml: 
              schema: books-jsonschema
              example: |
                <?xml version="1.0" encoding="UTF-8"?>
                <book>
                  <price></price>
                </book>
            application/json: 
              schema: books-jsonschema
              example: |
                {
                  "book" : {
                    "price" : ""
                  }
                }
  /{id}: 
    get: 
      responses: 
        200: 
          body: 
            application/xml: 
              schema: book-jsonschema
              example: |
                <?xml version="1.0" encoding="UTF-8"?>
                <book>
                  <price></price>
                </book>
            application/json: 
              schema: book-jsonschema
              example: |
                {
                  "book" : {
                    "price" : ""
                  }
                }

Homogenous Multidimensional Array Support in JSON Documents

You can select a JSON sample with homogenous multidimensional arrays when configuring the REST Adapter in the Configuration Wizard.

All JSON messages must be converted to XML before they can be processed by Oracle Integration Cloud Service at runtime. Semantically, there is no equivalent of multidimensional arrays in XML. To support multidimensional arrays, intermediate XML elements are generated that denote the beginning and ending of a nested array. When receiving a JSON message containing multidimensional arrays, these reserved elements are injected into the generated XML to denote the beginning and ending of a nested array. While converting XML elements back into JSON, the injected elements are converted into JSON with nested arrays.

The following JSON document consists of a multidimensional array (@ref "rercordsData”).

{
    "studentData": {
        "fieldNames": [ "id","mobile_number" ],
        "recordsData": [ ["21","23"], ["+91123456789", "+91987654321" ]  ],
        "name": "jack"
    },
    "schoolData": {
        "Name": "ABCInternations",
        "StudentNumbers": 1300,
        "Address": "YYY streets Sector-44 India"
    }
}

The sample generated schema XML for the JSON document looks as follows:

<?xml version = '1.0' encoding = 'UTF-8'?>

<ns0:executeResponse xmlns:ns1="http://xmlns.oracle.com/cloud//REST/test/types" 
xmlns:ns0="http://xmlns.oracle.com/cloud//REST/test_REQUEST/types">

<ns1:response-wrapper>
  <ns1:studentData>
    <ns1:fieldNames>id</ns1:fieldNames>
    <ns1:fieldNames>mobile_number</ns1:fieldNames> 
    <ns1:recordsData>  
         <ns1:nestedArray>
                 <ns1:nestedArrayItem>21</ns1:nestedArrayItem>
                 <ns1:nestedArrayItem>23</ns1:nestedArrayItem>
         </ns1:nestedArray>
                         <ns1:nestedArray>
                                         <ns1:nestedArrayItem>+91123456789</ns1:nestedArrayItem>
                                         <ns1:nestedArrayItem>+91987654321</ns1:nestedArrayItem>
                         </ns1:nestedArray>
         </ns1:recordsData>
    <ns1:name>jack</ns1:name>
  </ns1:studentData>
  <ns1:schoolData>
        <ns1:Name>ABCInternations</ns1:Name>
        <ns1:StudentNumbers>1300</ns1:StudentNumbers>
        <ns1:Address>YYY streets Sector-44 India</ns1:Address>
   </ns1:schoolData>
</ns1:response-wrapper>
</ns0:executeResponse>

Elements in the nested array appear as nestedArray in the mapper and items in the elements appear as nestedArrayItem. You must map nestedArray as a for-each statement and nestedArrayItem as a for-each statement.
Description of ics_md_jsonl.png follows
Description of the illustration ics_md_jsonl.png

Multipart Attachment Support for Trigger and Invoke Connections

The REST Adapter supports multipart attachments for trigger (inbound) and invoke (outbound) requests.

For example, you can send a review document attachment with the trigger (inbound) REST Adapter to an invoke (outbound) Adobe eSign or DocuSign for delivery to the downstream endpoint for signing.

If you want to send attachments from inbound to outbound (in request messages) or to download attachments from outbound to inbound (in response messages), then for each attachment you must map the attachmentReference from source to target in the mapper.
Description of ics_rest_multpart_map.png follows
Description of the illustration ics_rest_multpart_map.png

If you do not map attachmentReference in the mapper for a request, the outbound REST Adapter does not receive attachments from the inbound direction (multipart request). Similarly, if you do not map attachmentReference in the mapper for a response, the inbound REST Adapter does not receive attachments from the outbound REST Adapter (multipart response).

It is important to understand the data structures of different types of configurations made using the REST Adapter or any application adapter exposing the REST API (used as a trigger) or consuming the REST API (used as an invoke).

There are two configuration categories of multipart request and response:

  • A — Multipart/mixed or multipart/form-data configured with JSON or XML samples

    This configuration uses the attachments schema and payload schema. The payload schema is derived based on a sample JSON/XML schema provided during configuration in the Adapter Endpoint Configuration wizard.

  • B — Multipart/form-data with HTML form payload

    Note:

    This category is used when you select Request is HTML Form in the Request page of the Adapter Endpoint Configuration wizard. This is similar for a response if you select Response is HTML Form in the Response page of the Adapter Endpoint Configuration wizard.

    This configuration uses the attachments schema and a generic schema with a ParameterList element. The ParameterList element consists of an unbounded parameter element. Each parameter has a name attribute. The value of the parameter is set directly to the parameter element. If there are multiple parameters, the parameter element can be repeated in the mapper. The datatype of the parameter and name is string.

Note the following details about both configuration categories:
  • Attachments schema

    The attachments element has an unbounded attachment element. This configuration supports receiving (on the source) or sending (on the target) multiple attachments. Each attachment element has attachmentReference and attachmentProperties.

  • The AttachmentReference element contains the location where the attachment has been staged for access.

    The AttachmentProperties element provides metadata about a single attachment:
    • The contentId property sets the Content-ID header of the body part. The Content-ID header sets a unique ID for the body part.

    • The contentType property sets the Content-Type header of the body part. For example, if a PDF file is sent, the contentType property should be application/pdf. If the source is providing a multipart attachment, this is determined automatically. The mapper can set/override these values.

    • The transferEncoding property sets the Content-Transfer-Encoding header of the body part. This header's value is a single token specifying the type of encoding:

      Content-Transfer-Encoding := "BASE64" / "QUOTED-PRINTABLE" / 
                                   "8BIT"   / "7BIT" / 
                                   "BINARY" / x-token

      These values are not case sensitive. That is, Base64, BASE64, and bAsE64 are all equivalent. An encoding type of 7BIT requires that the body is already in a seven-bit, mail-ready representation. This is the default value (that is, Content-Transfer-Encoding: 7BIT is assumed if the Content-Transfer-Encoding header field is not present). See https://www.w3.org/Protocols/rfc1341/5_Content-Transfer-Encoding.html.

    • The partName property sets the fileName of the body part. The attached file/body part is saved by the target system with this name.

    • The contentDisposition property sets the Content-Disposition header of the body part.

      In a multipart/form-data body, the HTTP Content-Disposition is a header to use on the subpart (that is, the attachment) of a multipart body to provide information about the field to which it applies. The Content-Disposition header value is generally set to form-data. The optional directive name and filename can also be used. For example:

      Content-Disposition: form-data
      Content-Disposition: form-data; name="fieldName"
      Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"
    • The contentDescription property sets some descriptive information with a given body part. For example, you can mark an image body as a picture of the Space Shuttle Endeavor. You can place such text in the Content-Description header field.

    • The fileInputHtmlFieldName property sets the name of the part from which the server must read the file.

Mapper configuration scenarios:
  • Both source and target have multipart requests with JSON/XML payload (category A)

    The following sample map focuses only on the mapping of attachmentReference to the target. In this scenario, there is an assumption that only one attachment from the source is being mapped to the target. The mapping of the payload (request-wrapper node) between the source and target is not shown. You must perform that task.


    Description of rest_multipart_1.png follows
    Description of the illustration rest_multipart_1.png
  • Source is multipart/mixed or multipart/form-data with JSON/XML payload (Category A). Target is multipart/form-data with form fields (Category B)

    The following map focuses on mapping of the attributes on the HTML form. There must be as many parameters in the parameterList as there are fields in the HTML form.


    Description of rest_multipart_2.png follows
    Description of the illustration rest_multipart_2.png
  • Creating reference from base64–encoded content. The source has a base64–encoded string and the target can be any of the three: multipart/mixed, multipart/form-data with JSON/XML payload, or multipart/form-data with HTML form payload.

    In the inbound payload, the content element is a base64–encoded string. This can be sent as an attachment in the outbound request.

    Since the inbound request is not multipart, but the outbound must be multipart, you must set multipart-specific properties in the mapper for the outbound direction. The contentType is set here to image/png, partName is set to picture.png, and fileInputHtmlFieldName is set to image. The assumption is that the target system is configured to read from a body part having name="image" in its content disposition. This is done with the element fileInputHtmlFieldName.
    Description of rest_multipart_3.png follows
    Description of the illustration rest_multipart_3.png

    The base64 string can be converted into a reference using XSL function decodeBase64ToReference and the reference can be assigned to the attachmentReference element.

    Description of rest_multipart_4.png follows
    Description of the illustration rest_multipart_4.png
  • The inbound is an FTP file read operation (nonmultipart) and the outbound is multipart/mixed with a JSON or XML payload.


    Description of rest_multipart_5.png follows
    Description of the illustration rest_multipart_5.png

Note:

  • If the source is not multipart, but the target must be multipart, contentType and partName must be provided for the target through the mapper.

  • The response mapper description is similar to the request mapper.

On-Premises REST API Support with the Agent

Oracle Integration Cloud Service provides an agent framework that enables you to create integrations and exchange messages between on-premises applications and Oracle Integration Cloud Service. You can integrate on-premises REST APIs with Oracle Integration Cloud Service through use of the on-premises agent. Once you create an agent group and install the on-premises agent, you can create and configure a REST Adapter connection as follows:

  • Select REST API Base URL or Swagger Definition URL from the Connection Type list and enter the appropriate URL in the Connection URL field of the Connection Properties dialog. No other connection types are supported.

  • Select Basic Authentication or No Security Policy from the Security Policy list of the Credentials dialog. No other security policies are supported.

  • Select the previously-created agent group in the Select an Agent Group dialog.

For conceptual information about the on-premises agent, see About Agents and Integrations Between On-Premises Applications and Oracle Integration Cloud Service. For information about creating an agent group and installing the on-premises agent, see Managing Agent Groups and the On-Premises Agent.

Viewing the Metadata for the Inbound REST Endpoint in Swagger Format

You can view the metadata of an activated REST integration and then append /swagger to the metadata URL to view the Swagger format for the integration.  The inbound REST integration can then be exposed as a Swagger connection.

  1. On the Integrations page, find the integration whose endpoint URL you want to use.

  2. Click the Details icon at the far right.

  3. Click the Endpoint URL value (for example, http://myPODname:7002/integration/flowapi/rest/GET_ONE_BOOK/v01/metadata).

  4. Append /swagger to the end of the URL, and press Enter.

    Appending /swagger to the URL generates a Swagger document for the inbound integration. This URL can also be used to create a new Swagger connection in the Connection Properties dialog. You enter the Swagger URL in the Connection URL field and select Swagger Definition URL from the Connection Type field.
    Description of swagger_connection_url.png follows
    Description of the illustration swagger_connection_url.png

RFC 3986 Support for Encoding Query Parameters

The REST supports encoding query parameters in accordance with RFC 3986 standards. The default behavior is to encode the query parameters following the application/x-www-form-urlencoded scheme. For most older services that expect query parameters to be encoded following the application/x-www-form-urlencoded scheme, the default scheme should work. If you find the target endpoint not behaving correctly with the default encoding scheme, the REST can also be configured to strictly follow RFC 3986. A very common scenario in which the default behavior may not be desirable is when the target service expects space characters encoded as %20 in the query parameters. In this case, the default behavior is to encode space characters as +. Some new services may also respond with HTTP 400 (bad data) if query parameters are encoded in the application/x-www-form-urlencoded scheme. In these cases, you can switch to the RFC 3986 standard and check if the service responds correctly. To use RFC 3986 (and override the default behavior), perform the following steps to configure the REST as an invoke connection (and not as a trigger connection) in the Endpoint Configuration Wizard and in the mapper.

  1. On the Basic Info page, select the Custom check box for Configure Request Headers.

  2. On the Request Headers page, add the x-ics-use-x-www-form-urlencoded custom header and optionally provide a description.

  3. Complete the wizard.

  4. In the mapper, set the x-ics-use-x-www-form-urlencoded custom header to false.

The REST automatically encodes all query parameters in accordance with RFC 3986 in the outgoing request for this invoke connection.

Support for application/octet-stream MIME Attachment (Raw) Payloads

A MIME attachment with the content type application/octet-stream is a binary file. Typically, it is an application or a document that is opened in an application such as a spreadsheet or word processor. If the attachment has a filename extension associated with it, you may be able to determine what type of file it is. For example, a .exe extension indicates a Windows or DOS program (executable), while a file ending in .doc is probably meant to be opened in Microsoft Word.

The application/octet-stream MIME type is used for unknown binary files.  It preserves the file contents, but requires the receiver to determine file type, for example, from the filename extension. The Internet media type for an arbitrary byte stream is application/octet-stream.

To use this feature, select the Raw option from the invoke Request/Response page when configuring the adapter as an invoke. When you select this option, you need not provide a schema because the payload has no structure. 

This feature works with the application/octet-stream MIME type and any other type that can be sent as raw bytes. For example, the REST Adapter can send outbound requests or process outbound responses using the application/pdf, application/zip, image/jpeg, image/png, and other formats. Commonly used types shown in the dropdown are:

  • application/octet-stream

  • application/pdf

  • application/msword

  • application/zip

  • image/jpeg

  • image/png

  • image/bmp

  • image/gif

There is also a text box you can use to provide a type not listed in the dropdown list—for example, video/mp4 or text/csv.

The following screenshots show how raw payloads can be mapped.





Complex Schema Support

Support is provided for XSDs that can import and include other XSDs. The included XSDs in the ZIP file can import the XSD from an HTTP location. All XSD files must be added to a ZIP file and uploaded when configuring the REST Adapter in the Adapter Endpoint Configuration Wizard.

In the following example, the hierarchy of the ZIP file to upload is as follows:

zipxsd.zip
  first.xsd
  second (folder)
    second.xsd
first.xsd imports second.xsd.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:tns="http://xmlns.oracle.com/first" 
targetNamespace="http://xmlns.oracle.com/first" 
      xmlns:tns1="http://xmlns.oracle.com/second"> 
<xs:import schemaLocation="./second/second.xsd" 
targetNamespace="http://xmlns.oracle.com/second"/>
<xs:import schemaLocation="https://example.com/fscmService/ItemServiceV2?
XSD=/xml/datagraph.xsd" targetNamespace="commonj.sdo"/>
<xs:element name="book"> 
  <xs:complexType> 
    <xs:sequence> 
      <xs:element name="isbn" type="xs:string"/>
      <xs:element name="title" type="xs:string"/> 
      <xs:element name="author" type="tns1:author"/> 
    </xs:sequence> 
  </xs:complexType>  
</xs:element> 
</xs:schema>
The contents of second.xsd are as follows.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:tns="http://xmlns.oracle.com/second" 
targetNamespace="http://xmlns.oracle.com/second"> 
<xs:import schemaLocation="https://example.com/fscmService/ItemServiceV2?
XSD=/mycompany/apps/scm/productModel/items/itemServiceV2/ItemAttachment.xsd" 
targetNamespace="http://xmlns.oracle.com/apps/scm/productModel/items/itemServiceV2/"/>
<xs:complexType name="author">
    <xs:sequence> 
       <xs:element name="name" type="xs:string"/>  
       <xs:element name="address" type="xs:string"/> 
    </xs:sequence> 
</xs:complexType> 
<xs:element name="Admin">
    <xs:complexType>
          <xs:sequence>
             <xs:element name="AdminName" type="xs:string"/>
             <xs:element name="AdminAdd" type="xs:string"/>
          </xs:sequence>
    </xs:complexType>
</xs:element>
</xs:schema> 

Note:

If you are importing from HTTPS locations, ensure that you import the SSL certificates into Oracle Integration Cloud Service.