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.

See Configure Connection Security.

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.

1. 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.

2. If the Swagger resource is protected, provide the necessary security configuration and test and save the connection.

3. 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.

4. Select the business object and the operation to invoke the object in the Adapter Endpoint Configuration Wizard.

5. Complete the wizard and the mappings.

6. Activate and invoke the flow.

See Configure Connection Properties for Invoke Connections.

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.

1. 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.

2. If the resource is protected, provide the necessary security configuration and test and save the connection.

3. 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.

4. Select the business object and the operation to invoke the object in the Adapter Endpoint Configuration Wizard.

5. Complete the wizard and the mappings.

6. Activate and invoke the flow.

See Configure Connection Properties for Invoke Connections.

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.

The endpoint URL to invoke can also be invoked using the following CURL command:

curl -X GET https://api.carbonintensity.org.uk/intensity/date  -H 'Accept: application/json'

The response is of the form:

{"data":[ {"from": "2018-01-20T12:00Z",
    "to": "2018-01-20T12:30Z",
    "intensity": {
      "forecast": 266,
      "actual": 263,
      "index": "moderate"
    }
}]
}

1. 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.

2. 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.

3. 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.png
   

   Because the options corresponding to request payload, request parameters (query and template parameters), and request headers were not selected, the corresponding pages are skipped.

4. Select the required payload format and provide a sample JSON, XML, or schema that represents the payload.

   
   
   
   Description of the illustration rest_adapter_response.png
   
   

   A JSON sample can also be provided using the <<<inline>>> option.

   
   
   Description of the illustration rest_adapter_json_spl.png
   

5. Complete the rest of the Adapter Endpoint Configuration Wizard.

6. 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.

1. Create a connection with a REST Adapter invoke connection for the target service to consume.

2. Drag the connection onto the integration canvas.

3. On the Basic Info page, provide the HTTP verb and the relative request URI.

4. Select Custom in the Configure Request Headers section.

   The REST Adapter shows a page for you to configure the custom request headers.

5. 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.

6. 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.

1. On the Connections page for the REST Adapter, go to the Connection Properties section. At a minimum, specify the following details.
2. From the Connection Type list, select REST API Base URL.
3. In the Connection URL field, specify the endpoint URL according to the service you want to use. The REST Adapter exposes dynamic endpoint support. For example:

   https://amazonaws.com

4. Go to the Security section.
5. From the Security Policy list, select AWS Signature Version 4.
6. Specify the following details.

   Element	Description
   Access Key	Enter the access key obtained when you created your Amazon security credentials.
   Secret Key	Enter the secret key obtained when you created your Amazon security credentials.
   AWS Region	Select the region in which the AWS server is hosted.
   Service Name	Select the AWS service to which to connect.