REST Adapter Restrictions

Note the following REST Adapter restrictions.

  • REST endpoints can be protected using two-way SSL or mutual TLS authentication (mTLS). The REST Adapter supports accessing these endpoints. Authorization endpoints that procure and manage OAuth access tokens are also REST endpoints. However, these endpoints are not certified for use with the REST Adapter connection when protected using two-way SSL.
  • The maximum permissible limit for JSON file samples is 100 KB.

  • Plain/text content-type can be sent or received as unparsed content by the REST Adapter using the raw payload option.

  • Consuming external REST APIs that are protected using NTLM or digest token-based authentication are not supported.

  • When configuring the REST Adapter to work with the on-premises connectivity agent on the Connections page, only the Basic Authentication and No Security Policy security policies in the Security Policy list are supported. No other security policies are supported. See On-Premises REST API Support with the Agent.
  • 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.

  • Multipart/mixed data and polymorphic constructs are not supported when publishing OpenAPIs.
  • Unicode characters in the range of \u0000 to \u001F are control characters and are not allowed in JSON elements.
  • You can customize the response status. However, this is not shown as part of the Swagger contract because runtime overrides are not known as part of the interface.
  • HTTP response status cannot be customized under the following conditions:
    • If the request is asynchronous one way. This is because the response status is always 201.
    • Errors that occur during trigger request/response handling are reported using a predefined error code.
    • Basic routing integrations (map my data integrations) don't allow fault handling and error responses in such scenarios.
    • If the HTTP response status is set to 204, the response is sent back without any content.

Note:

There are overall service limits for Oracle Integration. A service limit is the quota or allowance set on a resource. See Service Limits.

Swagger/OpenAPI Restrictions

Not all Swagger constructs are understood by the REST Adapter. Note the following limitations when publishing and consuming Swagger/OpenAPI.

Publish Restrictions

Endpoints created using the REST Adapter trigger connection are described using a Swagger and openAPI definition. REST endpoints having the following characteristics are not correctly described. Clients must not rely on the Swagger/openAPI definition in these cases:
  • REST endpoints having attachments with multipart/mixed content in request/response
  • REST endpoints having an XML request/response

Each REST Adapter trigger connection endpoint is published as a Swagger document. The Swagger document usually has a single resource and verb.

However, in the case of multiple verbs and resources (MVRP), the Swagger document has multiple resources or paths in Swagger and multiple verbs for each resource.

Consume Restrictions

The REST Adapter as a client can be configured with a Swagger definition based on which it can discover and list the existing resource. However, some Swagger operations cannot currently be correctly consumed by the REST Adapter:
  • Multipart/mixed
  • Raw/application/octet-stream
  • XML
  • Top-level array
  • Multipart-formdata
  • External REST APIs that are described using OpenAPI 3.0
  • Swagger documents of external REST APIs that have metadata regarding content types such as multipart/form-data, multipart/mixed, and application/octet-stream
  • REST Adapter invoke connections cannot consume Swagger documents with recurring nested structures. For example:
    Employee → payroll → item (line 1, line2)
    Manager → payroll  → item (line 3, line4)

    In such a case, the Swagger parser caches the first definition of item and uses that causing incorrect manager schema. This issue is addressed, but the fix is currently not enabled due to backward compatibility.

Publish Restrictions

Endpoints created using REST Adapter trigger connections are described using a Swagger and openAPI definition. REST endpoints having the following characteristics are not correctly described. Clients must not rely on the Swagger/openAPI definition in these cases:

  • REST endpoints having attachments with multipart/mixed content in request/response
  • REST endpoints having an XML request/response

Each REST Adapter trigger connection endpoint is published as a Swagger document. The Swagger document usually has a single resource and verb.

However, in the case of multiple verbs and resources, the Swagger document has multiple resources or paths in Swagger and multiple verbs for each resource.

While OpenAPI lets you define dictionaries types where the keys are strings, dictionary types are not supported in Oracle Integration.

Consume Restrictions

The REST Adapter as a client can be configured with a Swagger definition based on which it can discover and list the existing resource. However, some Swagger operations cannot currently be correctly consumed by the REST Adapter:

  • Multipart/mixed
  • XML
  • Multipart-formdata
  • External REST APIs that are described using OpenAPI 3.0
  • Swagger documents of external REST APIs that have metadata regarding content types such as multipart/form-data, multipart/mixed, and application/octet-stream
  • REST Adapter invoke connections cannot consume Swagger documents with recurring nested structures. For example:

    In such a case, the Swagger parser caches the first definition of item and uses that causing incorrect manager schema. This issue is addressed, but the fix is currently not enabled due to backward compatibility.

    REST endpoints that do not have a request or a response cannot be consumed using a Swagger-based connection or using the local integration. If an error appears after initializing the local integration or the Adapter Endpoint Configuration Wizard with a Swagger-based connection, check the limitations on consumption of certain Swaggers.

Note these additional restrictions:

  • The missing server URL for the OpenAPI specification is resolved from the OpenAPI host port. If the server URL is missing from the OpenAPI specification, the base URL is resolved from the domain/host:port of the OpenAPI URL where the OpenAPI specification is hosted. For an example, the target endpoint is resolved using the host and port where the OpenAPI specification is hosted as follows:
    http(s)://host:port/path-from-openapi
  • Headers/custom headers must be added manually and are not discovered from the OpenAPI specification.
  • Connectivity agent limitations:
    • Swagger API consumption does not work with the connectivity agent.
    • OpenAPI consumption does not work with the connectivity agent.
  • If a Swagger or OpenAPI specification defines multiple success responses, Oracle Integration uses the responses based upon the following criteria:
    • Oracle Integration first looks for a success response (200).
    • If the definition does not contain a 200 response, Oracle Integration looks for a response definition with default.
    • If default is not defined, Oracle Integration looks for a response with a 201 definition.

    In each category, Oracle Integration first uses the response corresponding to application/json. Otherwise, Oracle Integration uses the first response in the list of responses for the status code.