2 REST Adapter Concepts

The following sections describe REST Adapter capabilities in more detail.

Topics:

Configuration Parameters

You configure the following parameters using the Adapter 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 Adapter Endpoint Configuration Wizard automatically start appearing in the mapper. 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 Adapter Endpoint Configuration Wizard automatically start appearing in the mapper. You can map the header properties in the mapper. See Create Routing Paths for Two Different Invoke Endpoints in Integrations and Create 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

  • API Key Based Authentication

  • OAuth 1.0a One Legged Authentication

  • Amazon Web Services (AWS) Signature Version 4

  • Oracle Cloud Infrastructure (OCI) Signature Version 1

See Configure Connection Security for Invoke Connections 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 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.

Specify the OAuth custom two-legged flow and three-legged flow security policies. See Configure Connection Security for Invoke Connections and REST Adapter Use Cases.

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 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 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 Adapter 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 Adapter 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 Adapter Endpoint Configuration Wizard.

All JSON messages must be converted to XML before they can be processed by Oracle Integration 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).

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

    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:

    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.
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
  • The source is multipart/mixed or multipart/form-data with JSON/XML payload (Category A). The 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 a 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 provides an agent framework that enables you to create integrations and exchange messages between on-premises applications and Oracle Integration. You can integrate on-premises REST APIs with Oracle Integration with the on-premises connectivity 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. For information about creating an agent group and installing the on-premises agent, see Manage the Agent Group and the On-Premises Connectivity Agent.

View 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 Adapter 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 Adapter 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 Adapter as an invoke connection (and not as a trigger connection) in the Adapter 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 Adapter Endpoint Configuration Wizard.

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

The REST Adapter 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 (Binary) 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, an .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 Binary option from the invoke Request/Response page when configuring the adapter as an invoke. When you select this option, you do not need to 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 binary 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 to provide a type not listed in the dropdown list (for example, video/mp4 or text/csv).

The following screenshots show how binary payloads can be mapped.





Security is Not Required for Swagger Definition and Metadata Catalog URL Connections

Upon activation of an integration with a REST Adapter used as a trigger, a metadata link is produced with documentation that describes the Oracle Integration REST endpoint. A Swagger description is also produced so other APIs can also consume the Oracle Integration REST endpoint. The Swagger and metadata artifacts that correspond to the Oracle Integration REST endpoint are unprotected.

The Oracle Integration REST endpoints are still protected, just the Swagger and metadata artifacts have been made unprotected to enable better discovery from third party APIs.

REST Endpoint Metadata and a Swagger Link to a REST Metadata Description

When you activate an integration with a REST Adapter trigger connection, an endpoint metadata URL link is provided at the top of the Integrations page. For example:
integration Hello World (1.1.0) was activated successfully.
You can access it via http://host:port/ic/api/integration/v1/flows/rest/HELLO_WORLD/1.0/metadata.

This link enables you to inspect the shape of the API. The metadata includes additional information about the endpoint description, the endpoint URI, and the Swagger URI.

Note the following details:

  • If you import an IAR file with an endpoint description defined in the inbound (trigger) direction, update the connection, activate the integration, and access the metadata in a browser (for example, through a URL similar in structure to the following), the endpoint description is not shown even though the inbound direction has a description defined.

    http://host:port/ic/api/integration/v1/flows/rest/OLD_INTG_DESC/1.0/metadata

    This is expected behavior. The description is stored in a JCA file from which it is read and displayed. Existing integrations do not have this file. Even after upgrades, the existing integration does not show the endpoint description. To get the correct description, you must re-edit the REST Adapter to generate the artifacts again and re-activate the integration.

  • If you attempt to re-edit an imported integration or existing integration in the Adapter Endpoint Configuration Wizard with a resource URI of /metadata or /metadata/swagger, you cannot navigate the wizard and receive an error. This is because the /metadata or /metadata/swagger keywords are reserved.

  • If the relative URI has template parameters, then at runtime the value of the relative URI if resolved to /metadata or /metadata/swagger is treated as reserved for retrieving the integration metadata. Note the following behavior:
    • /{param}: Allowed - The integration cannot be invoked with the value of param as metadata and returns the metadata page.

    • /{param}/swagger: Allowed - The integration cannot be invoked with the value of param as metadata and returns the Swagger page.

    • /metadata/{param}: Allowed - The integration cannot be invoked with the value of param as Swagger and returns the Swagger page.

  • Metadata and Swagger are only served depending on predefined reserve URIs for an integration. Resources with arbitrary URIs ending with values metadata or swagger are not confused with the endpoint documentation artifacts.

Support for Dynamic REST Endpoints

The REST Adapter enables you to dynamically change the (invoke) outbound endpoint configuration. This feature is useful in the following scenarios:
  • A REST endpoint is required to be invoked dynamically or an endpoint is not known at design time.

  • Multiple REST services must be invoked, all of which accept the same input payload and return the same response payload as configured for the outbound endpoint. For such cases, this feature eliminates the need to create multiple connections for invoking each of these REST endpoints.

To change the endpoint configuration at runtime, you must provide a mapping for one or more of the various properties under ConnectivityProperties.

For example, the following steps describe how to configure an integration to invoke a REST endpoint determined at runtime:

  1.  Create and configure a REST Adapter as an invoke connection.

  2. In the target pane of the mapper, expand RestApi under ConnectivityProperties. These elements are made available automatically through a static schema that is added to the user-provided schema.

  3. Using the source schema in the source pane, create a mapping to AbsoluteEndpointUri in the target pane. Alternatively, you can also provide a static mapping. The REST Adapter uses the runtime value provided by this mapping to determine the REST endpoint to which to route this request.

  4. You can similarly provide a source mapping to other target nodes under ConnectivityProperties. The REST Adapter uses the runtime values provided by these mappings to dynamically configure the request.

  5. Activate and invoke the integration. The REST Adapter now invokes the endpoint URI determined at runtime.

  6. Hover the mouse pointer over these properties in the mapper for a brief description. These descriptions are also provided below:

    • AbsoluteEndpointUri: Represents the absolute endpoint URL that the REST Adapter invokes. Empty values are ignored. To route the request to an endpoint URL determined at runtime, provide a mapping for this element. AbsoluteEndpointUri takes first precedence among other URL-related properties under ConnectivityProperties.

    • BaseUri: The equivalent of the base URL provided during connection configuration. To substitute only the base URI and keep the rest of the URL the same, provide a mapping for this element. The mapping is ignored if AbsoluteEndpointUri has a runtime value.

    • RelativeUri: Forms the part of the endpoint URI between BaseUri and ?. This mapping has no impact if BaseUri has an empty runtime value or AbsoluteEndpointUri has a runtime value. The runtime value must start with a /.

    • Uri: Use the various elements under this node to substitute the specific parts with runtime values of an endpoint URL.

      • Scheme: Provide a mapping if you want to change only the scheme of the endpoint URL. The only supported values are HTTP and HTTPS.

      • Host: Provide a mapping if you want to change only the host of the endpoint URL.

      • Port: Provide a mapping if you want to change only the port of the endpoint URL.

      • Query: Provide a mapping if you want to change only the query portion of the endpoint URL. The query portion follows the ?.

      • Path: Provide a mapping if you want to change only the path portion of the endpoint URL. A path is the part of a URI between the hostname and ?.

    • Plugin: The various properties under this node impact the way the REST Adapter invokes the endpoint URL.

      • PostQueryString: When the runtime value is true and the HTTP verb is POST, the query string parameters are sent in the POST as form parameters. The default value is false.

      • UseFormUrlEncoding: When the runtime value is false, the REST Adapter uses RFC–3986 compliant encoding to encode the query parameters. The default value is true (the equivalent of setting custom header x-ics-use-x-www-form-urlencoded to false). See section “RFC 3986 Support for Encoding Query Parameters” for more information on x-ics-use-x-www-form-urlencoded. The x-ics-use-x-www-form-urlencoded custom header takes precedence when both properties are set.

Note the following restrictions:
  • The request and response schema must be the same as provided during configuration in the Adapter Endpoint Configuration Wizard.

  • Template parameters are not supported while mapping these properties.

  • An HTTP verb cannot be changed for the endpoint URL. For example, if the endpoint is configured to use POST, the outgoing request is a POST even if the endpoint URI changes at runtime.

  • Since the endpoint URL is determined at runtime, there is no facility to test whether the security credentials provided during connection configuration also work with the new endpoint URL. If the endpoint URL determined at runtime requires a different authorization header then the original URL, you may also have to provide a mapping for the authorization standard header.

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.

Nonstandard JWT Token Support

The use of nonstandard JWT tokens is supported. The JSON content type is a standard JWT token, while all other (for example, text or XML) are nonstandard JWT tokens. To fetch nonstandard JWT tokens from a REST service, use the following regex string.

  • Use regex “.*” if the entire content is a JWT token. For this example, the entire content of the sample HTTP response is JWT token.
    HTTP/1.1 200 OK
    Date: Wed Jul 4 15:38:53 2012
    Connection: Keep-Alive:
    Content-Type: text/plain;charset=UTF-8
    Content-Length: 148
    MTgwNzE5NTY1NToxQkhzQlpaSXM0a21BV3NhbVBIclJOTFM4OGFxU09jNlRTdmFKSmczLVBqVHlWRF
    JwbWYxOFhmcnN6S0N6c3Fzb1JKbEh6U2IwSTdvflVuZWFXVjVmemhJNTJ1YVN6bFdDbTBG
  • Use regex “(?:.*?"my_token":")(.*?)(?:".*?)”, if the JWT token is embedded inside a nonstandard response. For example, my_token is shown in the following sample HTTP response in which the JWT token is embedded inside a nonstandard response. This regex consists of a capturing group and noncapturing group. See https://www.regular-expressions.info/refcapture.html.
    HTTP/1.1 200 OK
    Date: Wed Jul 4 15:38:53 2012
    Connection: Keep-Alive:
    Content-Type: text/plain;charset=UTF-8
    Content-Length: 286
    "name":"raw-jwt"
    "my_token":"MTgwNzE5NTY1NToxQkhzQlpaSXM0a21BV3NhbVBIclJOTFM4OGFxU09jNlRTdmFKSm
    czLVBqVHlWRFJwbWYxOFhmcnN6S0N6c3Fzb1JKbEh6U2IwSTdvflVuZWFXVjVmemhJNTJ1YVN6bFdD
    bTBG"
    "id":"8353"

Oracle Cloud Infrastructure REST API Support with the OCI Signature Version 1 Security Policy

You can call the Oracle Cloud Infrastructure (OCI) REST API by configuring the REST Adapter connection to use the OCI Signature Version 1 security policy. OCI signature support in the REST Adapter enables a user to use Oracle Cloud Infrastructure services. For example, you can create an integration that calls Oracle Cloud Infrastructure to create a storage bucket.