1. Using the Rapid Adapter Builder with Oracle Integration 3
  2. Get Started with the Rapid Adapter Builder
  3. Use VS Code as an Integrated Development Environment
  4. Data Mapping in the Adapter Definition Document
  5. Data from an OpenAPI Document

Data from an OpenAPI Document

This section provides the mapping of data between an OpenAPI document and an adapter definition document, which is generated using the OpenAPI file.

Note:

If a property is marked Not Applicable (NA), it means the corresponding property is absent from the Postman collection that is used to generate the adapter definition document. In these instances, a default or fixed value is set in the adapter definition document.

Info Component

This topic provides the mapping of data for the Info component of the adapter definition document, generated using an OpenAPI file.

Property in OpenAPI Document Property in Adapter Definition Document Filled In During Conversion? Notes
"develop:" + info.title, where any non-alphanumeric character (including spaces) is replaced with a hyphen (-), and then truncated to the maximum character length (100) for an ID of the adapter definition document. id Yes If the title in the OpenAPI document is "Basemap styles service", the value for the ID field in the adapter definition document is: "develop:basemap-styles-service".
NA type No User-defined value.
info.title displayName Yes Title mapping.
info.description description Yes Description mapping.
NA version Yes Default value filled in is 1.0.0.
NA specVersion Yes Default value filled in is 1.0.
NA categories No User-defined value.
info.title appInfo.name Yes Mapping for the appInfo object in the adapter definition document; child objects can be empty.
info.contact.email appInfo.contactUs Yes
info.description appInfo.description Yes
info.contact.url appInfo.supportURL Yes
externalDocs.url appInfo.documentationUrl Yes
NA publisherInfo.name No User-defined value.
NA publisherInfo.description No
NA publisherInfo.contactUS No
NA publisherInfo.supportURL No
NA publisherInfo.documentationURL No
NA publisherInfo.releaseNotes No

Connection Component

This topic provides the mapping of data for the Connection component of the adapter definition document, generated using an OpenAPI file.

Property in OpenAPI Document Property in Adapter Definition Document Filled In During Conversion? Example or Notes
NA connectionProperties[].name Yes Fixed value. Set it to baseURL.
NA connectionProperties[].type Yes Fixed value: STRING.
NA connectionProperties[].displayName Yes Fixed value: Base URL.
NA connectionProperties[].required Yes

Fixed value: true.

NA connectionProperties[].hidden Yes

The value is true if there is an URI in openapi.servers; otherwise, it is false.

NA connectionProperties[].scope Yes Fixed value: single element array containing "ACTION".
NA connectionProperties[].tokenized Yes Fixed value: false.
The first URI in openapi.servers connectionProperties[].default Conditionally If openapi.servers is empty, this field won't be filled in.
components.securitySchemes. See Security Scheme Object. connectionProperties[].securityPolicies Yes
The following security policies are supported:
  • No Auth (if no security policy is provided)
  • Basic Authentication
  • Bearer Token Authentication
  • API Key
  • Implement OAuth 2.0 Resource Owner Password Flow
  • Implement OAuth 2.0 Client Credentials
  • Implement OAuth 2.0 Authorization Code

For information on how the security policies are implemented, see Learn About Security Policies for Invoke Connections.

During conversion, the Rapid Adapter Builder sets a default value for some fields for which it can infer values (such as, accessTokenUsage, oauth.access.token.uri, auth.auth.code.uri), and it sets those fields as hidden. However, you can modify the values in the adapter definition document.

Further, the following OpenAPI security schemes are implemented using the API-Key Based Authentication security policy:
  • HTTP Bearer Auth
  • API key auth
Here are some additional notes about the implementation and mapping of the above security schemes:
  • If there is only Bearer auth, the accessTokenUsage security property is resolved to "-H Authorization: Bearer ${api-key}” and is hidden.
  • If there is only API Key auth, the accessTokenUsage security property is resolved according to whether it is in the header or query, and then it's hidden.
  • If both Bearer auth and Api Key auth are present, the accessTokenUsage property is visible with the name Access token authentication.
    • If the API Key auth is in the header, the header field is combined (Example: "-H api_key: ${access_token} -H Authorization: Bearer ${api-key}”). As it is visible, you can choose which scheme to use.
    • If the API Key auth is a query parameter, the field is left blank.
Regarding the OAuth 2.0 security policies, here are some points to note with respect to OpenAPI documents:
  • OpenAPI lists all scopes available, so this is left blank and visible, and you can set your own scope.
  • Fields such as oauth.client.id, oauth.client.secret, username, password are left visible, and you can fill the same.
  • The fields oauth.access.token.uri and oauth.auth.code.uri exhibit the following behavior:
    • For context, all URIs in an OpenAPI document can be relative, so there is a complex behavior for the resolution of access token URI or authorization code URI. OpenAPI documents have a server URI that can be used to resolve relative URIs within the document. However, there can be multiple server URIs and they can be relative.

    • If a fully qualified URI can be unambigously resolved, it is set as the default value and this security property is hidden.

      This is true for the following scenarios: Either the provided access or auth URI is absolute, or there is one absolute base-server URI and the relative access or auth URI can be resolved against it.

    • If a fully qualified URI cannot be determined for access or authorization, the security property is set to visible with no default value that you can fill in.

      This is true for the following scenarios: Either the server is relative (to the URI where the OpenAPI document is hosted), or there are multiple servers, or the server invalid, or the access or auth URI is invalid.
NA securityPolicies[].type Yes

Fixed value: managed

Actions Component

This topic provides the mapping of data for the Actions component of the adapter definition document, generated using an OpenAPI file.

One OperationObject from an OpenAPI document is mapped to one action in the adapter definition document. For information on operation objects, see Operation Object.

The following example illustrates how an operation object in an OpenAPI document is converted to an action in an adapter definition document:
  • The operation-object data in an OpenAPI document: A GET operation to the object path "/webmaps/arcgis/imagery"
  • The corresponding action in an adapter definition document: webmapsArcgisImageryGetAction

Other action properties are mapped as follows:

Property in OpenAPI Document Property in Adapter Definition Document Filled In During Conversion? Example or Notes
OperationObject.summary or OperationObject.operationId displayName Yes If the summary isn't present, the operation ID is used as a fallback.
OperationObject.description description Yes NA
NA execute Yes Fixed value: flow:generalActionFlow.
NA input No Not necessary as an action can contain a reference to the OpenAPI path that maps to the action. From this reference, the input and output schema are derived. Example: "$refOpenapi": "POST:/pet"

However, actions that are not using OpenAPI can live alongside actions that use OpenAPI.
NA output No Not necessary as an action can contain a reference to the OpenAPI path that maps to the action. From this reference, the input and output schema are derived. Example: "$refOpenapi": "POST:/pet"

However, actions that are not using OpenAPI can live alongside actions that use OpenAPI.
HTTPMethod:pathName $refOpenapi Yes Example:

GET:/styles/arcgis/imagery
servers[0]+pathName configuration[0].default (path configuration field) Yes Every field (except default) is fixed. 
{
     "name": "path",
     "type": "TEXT_BOX",
     "displayName": "Path",
     "required": true,
     "readOnly": true,
     "hidden": true,
     "default": "/pet"
      }
servers[1]+methodName configuration[1].default (method configuration field) Yes Every field (except default) is fixed. 
{
     "name": "method",
     "type": "TEXT_BOX",
     "displayName": "Method",
     "required": true,
     "readOnly": true,
     "hidden": true,
     "default": "POST"
      }

Flows Component

This topic provides information for the Flows component of the adapter definition document, generated using an OpenAPI file.

During OpenAPI conversion, no information from an OpenAPI document is added to the Flows section of an adapter definition document. However, after conversion, the following default/generic flow is present in the adapter definition document.

"flows": {
    "generalActionFlow": {
        "id": "generalActionFlow",
        "version": "0.1",
        "start": "startState",
        "specVersion": "0.8",
        "functions": [
            {
                "name": "generalRestFunc",
                "operation": "connectivity::rest",
                "type": "custom"
            }
        ],
        "states": [
            {
                "actions": [
                    {
                        "name": "generalActionFlow",
                        "functionRef": {
                            "refName": "generalRestFunc",
                            "arguments": {
                                "uri": "${ .connectionProperties.baseURL + .configuration.path }",
                                "method": "${ .configuration.method }",
                                "parameters": "${ .input.parameters }",
                                "body": "${ .input.body }"
                            }
                        },
                        "actionDataFilter": {
                            "results": "${ { body: .body, headers: .headers } }",
                            "toStateData": "${ .output }"
                        }
                    }
                ],
                "name": "startState",
                "type": "operation",
                "end": true
            }
        ]
    }
}

Schemas Component

This topic provides information for the Schemas component of the adapter definition document, generated using an OpenAPI file.

As the adapter definition document references the OpenAPI schema ($refOpenAPI), no schemas are generated.

You can identify if an adapter definition document is driven by OpenAPI using the following characteristics:
  • The presence of "$refOpenapi" in some actions.
  • The parameter info.settings.supportsRegeneration set to true.