1. Using the REST Adapter with Oracle Integration Generation 2
  2. REST Adapter Concepts
  3. REST Endpoint Support
  4. Support for Dynamic REST Endpoints

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.

      • EnforceEmptyJSONObjectPayload: When set to true, sets the body payload to an empty JSON object. The default value is false.
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.