REST API Consumption Patterns
You can use the REST Adapter to implement the following common patterns to consume REST APIs.
Topics:
-
Configure the REST Adapter to Consume a REST API Protected with the API Key
-
Configure the REST Adapter to Consume an External REST API Described Using a Swagger Document
-
Configure the REST Adapter to Consume an External REST API Described Using a RAML Document
-
Configure the REST Adapter to Consume an External REST API with No Metadata Described in a Document
- Configure a REST Adapter to Consume a REST API that Expects Custom HTTP Header Properties
- Configure the REST Adapter to Consume an Amazon Web Services (AWS) REST API
Configure the REST Adapter to Consume a REST API Protected with the API Key
This section provides an overview of the API Key-Based Authentication security policy. This policy enables you to provide secure access to APIs. The resource owner generates an API key for a given client application with the required authorization and then shares the generated API key. The client application is then required to pass the API key with the request for accessing protected resources.
The following steps are performed as part of the API key-based authentication flow.
Step | Description |
---|---|
1 | The resource owner authenticates and generates an API key for the given client application. |
2 | The resource owner shares the generated API key with the client application. |
3 | The client application makes a request for a resource using the API key. |
On the Connections page of the REST Adapter, you select API Key Based
Authentication.
Description of the illustration api_key_based_auth.png
In the API Key Usage field, you specify how the API key is passed with the request for accessing a resource. Enter this information carefully since this usage governs how the provided API key is passed to the endpoint. See Configure Connection Security for details.
At runtime, the API key is automatically passed to the endpoint while sending the request.
Configure the REST Adapter to Consume an External REST API Described Using a Swagger Document
Oracle Integration can seamlessly integrate with REST APIs described using Swagger. The following example shows how to consume a Swagger-based REST API.
-
Create a REST Adapter connection by selecting Swagger Definition URL in the Connection Type field and specifying the URL pointing to the Swagger definition in the Connection URL field.
-
If the Swagger resource is protected, provide the necessary security configuration and test and save the connection.
-
Design an integration using the REST Adapter as an invoke connection. When the connection is used as an invoke, the REST Adapter automatically lists the operations and resources from the Swagger definition.
-
Select the business object and the operation to invoke the object in the Adapter Endpoint Configuration Wizard.
-
Complete the wizard and the mappings.
-
Activate and invoke the flow.
Configure the REST Adapter to Consume an External REST API Described Using a RAML Document
Oracle Integration can seamlessly integrate with REST APIs described using RAML. The following example shows how to consume a RAML-based REST API.
-
Create a REST Adapter connection by selecting RAML Definition URL in the Connection Type field and specify the URL pointing to the RAML definition in Connection URL field.
-
If the resource is protected, provide the necessary security configuration and test and save the connection.
-
Design an integration using the REST Adapter as an invoke connection. When the connection is used as an invoke, the REST Adapter automatically lists the operations and resources from the definition.
-
Select the business object and the operation to invoke the object in the Adapter Endpoint Configuration Wizard.
-
Complete the wizard and the mappings.
-
Activate and invoke the flow.
Configure the REST Adapter to Consume an External REST API with No Metadata Described in a Document
Oracle Integration can integrate with REST APIs that do not publish any service description. The following example shows how to integrate with these REST APIs. This example uses a publicly available API that provides carbon intensity data for the United Kingdom.
Note:
The REST Adapter provides support for consuming REST APIs that are described using the metadata catalog. However, because the metadata catalog as a standard is not being actively maintained, you are advised to not use the metadata catalog definition. Many applications have already moved their resource models to the OpenAPI Specification, which is the preferred metadata description for describing RESTful APIs. If the metadata catalog happens to be the only metadata definition, you have the option of directly consuming the target REST API using the request builder provided out of the box as part of the Adapter Endpoint Configuration Wizard.The API is described at https://carbon-intensity.github.io/api-definitions/#intensity
. In this example, an integration is modeled to fetch carbon intensity data. Because the API is not protected, no security configuration is required.
CURL
command:curl -X GET https://api.carbonintensity.org.uk/intensity/date -H 'Accept: application/json'
{"data":[ {"from": "2018-01-20T12:00Z",
"to": "2018-01-20T12:30Z",
"intensity": {
"forecast": 266,
"actual": 263,
"index": "moderate"
}
}]
}
-
Configure a connection by selecting REST API Base URL in the Connection Type field and providing the base URL of the service in the Connection URL field. See Configure Connection Properties for Invoke Connections.
Test and save the connection. Generally speaking, the REST API base URL should be the resource root of a REST API. In this example, the Connection URL field is configured as
https://api.carbonintensity.org.uk
.The following steps describe how to configure the relative REST resource in the Adapter Endpoint Configuration Wizard.
-
Configure the REST Adapter as an invoke connection. Oracle Integration determines the target endpoint URL by appending the relative resource URI to the base URL configured during connection configuration.
-
Provide a relative resource URI of
/intensity/date
and select the HTTP verb to use (GET for this example).In this example, a request payload is not required. Therefore, the corresponding option is not selected. The same applies for query and template parameters. However, since a response is expected, the option corresponding to a response is selected. The Adapter Endpoint Configuration Wizard determines the next page to show based on the options selected on this page.
Description of the illustration basic_info_response.pngBecause the options corresponding to request payload, request parameters (query and template parameters), and request headers were not selected, the corresponding pages are skipped.
-
Select the required payload format and provide a sample JSON, XML, or schema that represents the payload.
A JSON sample can also be provided using the <<<inline>>> option.
Description of the illustration rest_adapter_json_spl.png -
Complete the rest of the Adapter Endpoint Configuration Wizard.
-
Complete the mappings.
Description of the illustration rest_adapter_mapper.png
Configure a REST Adapter to Consume a REST API that Expects Custom HTTP Header Properties
The REST Adapter provides an easy and configurable way to consume an external HTTP service. You can configure the HTTP verb, resource URI, query and template parameters, HTTP headers, form parameters, body, and attachments that must be sent as part of the request.

Description of the illustration http_request.png
HTTP headers allow the client and the service to exchange additional information along with the request or the response. The Internet Assigned Numbers Authority (IANA) maintains a registry of standard or permanent HTTP request headers that are commonly used for predefined reasons. Along with the standard headers, services can also define custom proprietary headers for exchanging additional information.
Follow the steps mentioned below to invoke a REST service that expects a custom HTTP request header.
-
Create a connection with a REST Adapter invoke connection for the target service to consume.
-
Drag the connection onto the integration canvas.
-
On the Basic Info page, provide the HTTP verb and the relative request URI.
-
Select Custom in the Configure Request Headers section.
The REST Adapter shows a page for you to configure the custom request headers.
-
Define the proprietary header name and provide a brief description of the header.
Upon completion, the REST Adapter exposes the custom header specified above as part of the adapter request payload.
-
Assign this header a value using an assign action or the mapper. The assigned value is sent as a custom HTTP header to the target service at runtime.
Configure the REST Adapter to Consume an Amazon Web Services (AWS) REST API
You can configure the REST Adapter to consume an Amazon Web Services (AWS) REST API by selecting the AWS Signature Version 4 security policy on the Connections page. AWS provides a set of global compute, storage, database, analytics, application, and deployment services for consumption.