Best Practices for Building an Adapter

General Guidelines

Ensure that the behavior of your adapter is identical to the overall behavior exhibited by Oracle-delivered adapters with respect to adapter's participation in the life cycle of an integration flow, projects, and so on.
Develop your adapters iteratively. This mechanism of development and delivery is strongly supported in the Rapid Adapter Builder infrastructure.
This approach offers many benefits. For example, you can better track your time, deliver more frequent releases (if needed), respond to changing requirements more quickly, and test in isolation. Additionally, you won't be overwhelmed by needing to review and test a dozen or more APIs at one time.
In addition to starting small and iterating, Oracle recommends testing as you go. For instance, after specifying the requirements for a single API, test the adapter before you add the next API.
The level of testing is up to you. You might focus only on functional testing and save all other testing for after you've added all the required features to the adapter for the release; or you might opt for more extensive testing.
Keep the business process in mind while developing the adapter. The adapter should expose all capabilities needed for implementing the specific business process in Oracle Integration. For example:
- An adapter should ensure it exposes support for calling the downstream application APIs in case the business process you are targeting calls for Oracle Integration to send real-time updates to the downstream application.
- In case of a business process calling for create, update, or delete operations happening in the source application and relaying them to various systems, the adapter for the source application should support a trigger that has the capability to start the integration flow (in Oracle Integration) when changes occur to various resources in the source application.
Use versioning for changes or enhancements. The Rapid Adapter Builder allows for the delivery of multiple minor versions for a specific major version. At this time, the Rapid Adapter Builder supports only one major version for an adapter. See Rules for the Semantic Version Check.
Ensure that your adapter's latest minor version for a specific major version is validated against the latest Oracle Integration release, as and when your lower-level environment is patched with the latest Oracle Integration updates.
If the adapter that was working against the previous version of Oracle Integration starts encountering issues against the newer release, file service requests against Oracle Integration.
Ensure that all the appropriate tests and validations are done prior to publishing the next minor version.
Existing artifacts built against the preceding application version, connection, and integration flows (draft as well as deployed) should continue to work against the upgraded application versions seamlessly, without the need for customer intervention.
Ensure that your adapters can be used in/as the following artifacts:
- All integration patterns
- Global or project-specific adapter connections
- Shared adapter connections
- Any accelerator or recipe
Create documentation that helps integration developers work with your adapter.
Contact Oracle for the adapter documentation template to use and the adapter naming guidelines.

Connections Guidelines

General Connection Guidelines

Do not impose any limits on the following items:
- Number of endpoint configurations for a single connection—within a flow as well as across flows.
- Number of endpoint configurations having identical configuration.

Test-Connection Guidelines

Ensure that a Test connection invokes an idempotent (non-destructive) operation (HTTP GET) to a live endpoint with the fabricated payload, so that the service is consumable (outbound proxy, TLS versions, SSL handshake, authentication and authorization-related errors along with prescriptive recommendations needed to be rendered). See Implement the Test-Connection Behavior Using Flows.
Ensure that a Test connection fails and throws an appropriate message when the adapter tries to make an outbound connection to a non-supported application version.
Show the supported minimum and maximum releases in the error message.
Ensure that the Connection page presents the application prerequisites that need to be completed.

Connection Modification Guidelines

Ensure that the existing deployed Oracle Integration flows that leverage the your adapter continue to work without any deactivation/reactivation after the following changes to the connection:
- Password/API Key
- Security Policy (examples: HTTP Basic Auth to Username token; HTTP Basic Auth to OAuth Resource Owner Password Flow)
- Fresh consent for delegated authorization in case of OAuth flows (assuming there are no scope changes)
- Endpoint URL (assuming the new instance is identical to that of the existing instance – for example, application POD moved from 1 zone to another)
- Username (assuming the new user has the same privileges and roles as that of the previous user)
- Collection of additional connection metadata.

Guidelines for Adapter's Designtime, Runtime, and Life Cycle Management

Generally, your adapters should automatically discover new publicly-consumable business objects/APIs/events as they are introduced in the applications
- Do not introduce code changes to adapters that make the adapter consumers wait for the next adapter release to consume these objects.
- Make sure that Oracle Integration flows created after the availability of business objects/APIs are able to discover these objects.
You can develop adapters to target a specific business domain. You can code it to present actions specific to select business objects and operations.

Guidelines for Data Source Customizations

Ensure that custom objects and attributes are automatically discoverable.
Ensure that custom objects and custom attributes show the functional names in Oracle Integration (not field 1, field 2, and so on).
Ensure that the Regenerate option is available for adapters whose applications support customizations to the data models.
Ensure that a Re-edit of existing adapter configuration wizards automatically brings in the new custom objects and custom attributes.

Guidelines for Integration Flow Promotion or Applications Upgrade

Ensure that the integration flow archive (IAR) files (of the newly-built adapter) work against target application instance when imported into a higher Oracle Integration environment upon activation.
- Ensure that the adapter consumers are not asked to re-edit the adapter configurations in the higher Oracle Integration environment.
- Do not hard-wire external application or data source-specific endpoint details, which are stored in the adapter definition document.
Make sure that the application upgrades are transparent. Existing flows must work against an upgraded application instance without any changes, production outages, and patches.
Ensure that adapter consumers are not forced to create new connections to work against newer application releases or newer version of external data sources.
Ensure that adapter consumers do not have to deactivate and reactivate the existing flows (that reference your adapters) to work against the newer releases of an external application.
Optionally, in the subsequent minor versions of the adapter release, you can deliver the new infrastructure features added to applications (such as, support for new authentication/authorization policy, bulk data import, and so on).
Ensure that new flows work against latest application releases with no change or loss in behavior.
You must certify the adapters against the new versions of application releases.
- Ensure that you certify prior to the refresh of the Oracle Integration fleet with the newest application releases.
- Ensure that the existing automation tests are run to test the regressions, if any.
Ensure that your adapters work against all of the existing supported application versions.
Avoid situations where adapter consumers would need to upgrade to the most recently-delivered application release for the adapter to work.
However, your adapter may continue to have limited capabilities against older application releases.

Security Guidelines

Authentication or Authorization Guidelines

Ensure that the connection definition modeled in the adapter definition document for invocation of actions makes an attempt to support all of the authentication and authorization schemes supported by the external application.
Prioritize on exposing the most secured authentication or authorization schemes over the vulnerable ones.
Note that you cannot remove the authentication schemes implemented in the preceding version of an adapter; however, you can add new authentication schemes.

Transport Level Security Guidelines

Ensure external endpoints are secured using TLS v1.3 or v1.2.
Avoid support for TLS v1.1 and 1.0 protected endpoints.
Avoid calling external APIs protected using self-signed certificates or lesser-known CA-signed certificates. Oracle Integration flags adapters expecting this requirement and warns consumers subscribing to such adapters.
Ensure that the adapter development document advertises to the domains where the outbound requests need to be sent by the adapters. This information is presented to the consumers for their understanding. Oracle Integration flags adapters not having this information and warns consumers subscribing to such adapters.
Send requests in clear text without transport-level security. By default, the non-SSL support is disabled. Even though you can opt for supporting the transmission of data over the wire in non-encrypted mode (no TLS), it would have an adverse impact on the overall credit score, and Oracle Integration warns consumers subscribing to these adapters.

Versioning Guidelines

General Versioning Guidelines

Develop your adapters iteratively. This mechanism of development and delivery is strongly supported in the Rapid Adapter Builder infrastructure.
Use versioning for changes or enhancements. The Rapid Adapter Builder allows for the delivery of multiple minor versions for a specific major version. At this time, the Rapid Adapter Builder supports only one major version for an adapter. See Rules for the Semantic Version Check.
Ensure that the minor versions are backward compatible, and the integration flows built and deployed using the preceding minor version of an adapter continue to work without any manual intervention or disruptions, after the uptake of the latest and greatest minor version for that adapter by a consumer.

Connections Versioning Guidelines

Note that you cannot remove existing connection properties in the newer release.
You cannot make the new connection properties mandatory.
Do not change the functional behavior of the existing properties.
Ensure that the connections created with the older adapter release are usable for creating integration flows after the uptake of the newer version.
Ensure the existing deployed flows built on prior version of the adapter continue to work after the uptake of the newer version.
Ensure that your versioning does not require adapter consumers to deactivate and reactivate the existing flows.
Ensure that the newer adapter runtime handles the errors occurring in the existing metadata gracefully. (Ensure this even for the adapter changes done to fix the existing bugs or performance issues.)
Ensure that the new capabilities that you introduce in the newer adapter releases are opt-ins.
Ensure that the existing flows in draft mode (functionally complete) are deployable after the uptake of the newer version of the adapter. This should not result in adapter consumers having to configure the already-configured connections or re-edit the existing adapter configurations.

Guidelines for Oracle Integration Messages

Ensure that data structures generated using the newer minor version of an adapter are backward compatible. The maps built using the preceding version of the adapter should not be lost when existing endpoint configurations is reconfigured.
Ensure that the existing maps produced prior to the uptake of the newer minor version continue to work, both at design time and runtime after the uptake of the latest minor version.

Guidelines for Limits and Constraints

The Rapid Adapter Builder has limits for several areas. A limit is the quota or allowance for a resource. You must adhere to theses defined limits for your adapter. See Limits.

Source Control Guidelines

Ensure that Rapid Adapter Builder archive, containing the working version, is source controlled.