5 Work with Services

To access external REST APIs in your visual application, you create connections to the services that provide access to these API endpoints.

About Service Connections

To work with an external service's REST API, Visual Builder needs basic information about that service. A service connection provides this information by describing the connection to the service, including connection details, properties, and the REST endpoints provided by the service that you want to use in your application.

You can create a service connection in the following ways:
  • By selecting a service from a catalog of preconfigured Oracle SaaS/PaaS REST services
  • Providing a Swagger or ADF-Describe specification that describes the external service
  • Providing the location of a REST endpoint for the external service

A Visual Builder catalog of predefined services includes backends, such as Oracle Cloud Applications, Integration Applications, and Process Applications. These backends expose REST APIs that your visual application can consume right out of the box. You can also create custom backends to access services that aren't listed in this catalog, either by providing the service specification or by providing the URL of a REST endpoint of the service.

Use the Services tab in the Navigator to add new service connections and manage your existing ones. You can also manage your application’s catalog of backends here:
Description of service-connections-browser.png follows
Description of the illustration service-connections-browser.png

What Are Backends?

A backend is a collection of servers that your visual application uses to access REST endpoints in a known resource, like Oracle Cloud Applications or Oracle Integration.

Each backend is associated with one or more servers, and each server has different instances (say) for development, test, and production. These backend instances are defined in the Tenant Settings of your Visual Builder instance and provide the out-of-the-box catalog that all visual applications in your instance can access. Your application uses these backend definitions (instance URL, authentication type, and so on), in association with application profiles, to connect to the right server, so you can successfully develop, test, and deploy your application, as shown here:Description of backend-diagram-final.png follows
Description of the illustration backend-diagram-final.png

A typical backend catalog includes the built-in Integration, Oracle Cloud Applications, and Process backends. You can also create backends that map to other types of custom servers.

The catalog is described in an OpenAPI-compliant file called catalog.json, which contains the list of backends and their details at the tenant level. Because this definition applies to all visual applications, you can easily connect to REST APIs from the predefined catalog without having to specify instance URLs, authentication, and other details every time you create a visual application. You can choose to override the tenant-level definition for a single application, either to customize an existing backend (say, connect to a different instance or change the authentication mechanism) or to create your own—all of which is then stored at the application level in the services/catalog.json file.

When you create a service connection from a catalog, the service connection resolves using the backend configured at the application level and, if not present, it resolves to the backend configured at the tenant level.

A service connection can be associated with a backend, but it isn’t required to. You'll know when services are "derived" from a backend because you’ll see something like this:
Label in a service connection's Overview tab that says this service is based on a specific backend

Clicking the backend will take you to the Backends editor, where you can edit the backend’s details if you want.

Service Connections: Static Versus Dynamic

Service connections in Visual Builder are defined by the service's OpenAPI metadata, which describes the available endpoints and details required to connect to the service. How you want your connection to retrieve this service metadata—either statically or dynamically—is entirely up to you. Both options have their advantages and disadvantages.

Let’s say a service's OpenAPI definition is located at https://service.com/openapidef. You can set up your service connection to retrieve this definition in one of two ways:
  • To copy the service definition from https://service.com/openapidef at the time of development and save it to the visual application's sources. That is, statically retrieve the service metadata saved to the application when the service connection was first created—a static service connection.
  • To always get the service definition from https://service.com/openapidef. That is, dynamically retrieve the service metadata from the source URL each time you open the application—a dynamic service connection. The service definition in this case is only a "reference", a pointer to the OpenAPI document located outside Visual Builder.

Use the Metadata Retrieval Option on the service connection wizard to specify how you want the service metadata to be retrieved. You can choose the Dynamically retrieve metadata option if your service definition changes frequently and you want your application to include these updates, especially during the development stage when things are still evolving. Suppose the service owner adds a new field to the service definition and you want your application to have access to this field; creating a dynamic service connection will fetch the service metadata each time the application is opened and will pick up any changes made to endpoints (including the new field).

Note:

You can dynamically retrieve metadata only for service connections that provide a service specification or those derived from a catalog, specifically the Oracle Cloud Applications backend.

Dynamic service connections pull whole resources, rather than individual endpoints, which might make the openapi3.json metadata file verbose. If you include List of Value (LOV) endpoints as well, the size of the file increases even more. Coupled with factors such as complexity of the schema and network latency, dynamically retrieving metadata may take a while to retrieve and process. So if you need better runtime performance, choose the Copy full OpenAPI to your application option instead and select only the endpoints you need for your application. This way, your endpoint definitions will be stored locally in the application for faster retrieval.

You can create a dynamic service connection when your application is in development, then convert the dynamic connection to a static one when your application is ready for production. But a third recommended option—Copy minimal OpenAPI to the application—provides the best of both worlds when you create a service connection that points to an ADF Describe.

The Copy minimal OpenAPI to the application option is only available for services that are based on ADF Describe (like Oracle Cloud Applications' ADF BC-based REST APIs) and have a minimal describe endpoint to get limited metadata. This option stores service metadata for the endpoints you select in your application's sources, much like a static service connection, but it only copies the minimal describe for those endpoints. It also dynamically retrieves the parameter or request/response schema similar to a dynamic service connection. But it does this only when required (say, when a user tries to bind a table with an endpoint's response), not every time the app is opened. Because only the minimal OpenAPI is copied to your application and that too only for the endpoints you select, the size of the metadata file is reduced. And because the schema object is still referenced, the latest service definition is dynamically retrieved whenever required. For optimal runtime performance, this is the recommended option for ADF Describe-based services.

Here's a quick breakdown of the advantages and disadvantages of each metadata retrieval option:
Service Connection Option Advantage Disadvantage
Copy full OpenAPI to your application (Static) Better performance as service metadata is retrieved locally from the application's sources Application is out of sync from the latest service definition and might not have recent customizations. Also, because full service metadata (including child objects) is saved to the application's sources, runtime performance may be impacted if this metadata is very large. Optimizing your resources can help in reducing the fetch time of the static OpenAPI.
Dynamically retrieve metadata (Dynamic) Provides the most up-to-date service definition for your application Performance may be impacted, though not always
Copy minimal OpenAPI to the application (recommended) (Static + Dynamic)

Note:

Available only for ADF Describe-based services like Oracle Cloud Applications
Optimal performance as minimal service metadata is stored and can be retrieved faster from the application's sources; granular endpoint selection is also possible. Dynamically referenced schema objects provide the ability to retrieve the most up-to-date request/responses schema. Performance may be impacted when schema objects are retrieved

No matter which option you choose to create your service connection, you can switch it up any time you want, as described in Convert a Service Connection (Static to Dynamic or Dynamic to Static). You can also change things when you edit a service connection to add endpoints, as described in Add More Endpoints to a Service Connection.

What are Application Profiles?

Application profiles in Visual Builder facilitate the development of web and mobile apps that consume REST services.

As you develop your web and mobile apps, you need access to the REST services that your app will consume when it goes into production. Given that it may not be possible or appropriate to use production instances of the service as you develop your app, you use development and test instances that provide the same APIs as the production instance of the service for the development and test phases of application development.

To make the task of changing between development, test, and production instances easier, Visual Builder provides you with the ability to define application profiles in your visual application where you specify the appropriate details to use for an app when you deploy it to a development, test, or production environment. For example, basic authentication may be acceptable to use during the development of your application, but it is not recommended that you use this authentication type when you deploy your app to production. In this scenario, you can configure an application profile for development where you use the basic authentication mechanism that is less onerous to implement. The application profile that you use to deploy the app to production uses a more secure authentication mechanism.

Description of vb-app-profiles.png follows
Description of the illustration vb-app-profiles.png

You access application profiles from the Application Profiles tab of your visual application’s Settings page. Visual Builder provides one ready-to-use application profile (Base configuration) that is the default application profile to use when you deploy web and mobile apps in this visual application to development, stage, and production.

To create additional application profiles, click Duplicate and provide a new name (for example, Production configuration), ID, and description in the Duplicate Application Profile dialog. Having created the new profile, you can make it the default to use when you stage or publish your visual app by selecting the appropriate option from the menu that appears to the right of the newly created application profile:

Description of vb-app-profiles_prod-config.png follows
Description of the illustration vb-app-profiles_prod-config.png

The application profiles that you create can be associated with the various servers (dev, test, and prod) used by the REST service that your app consumes. In the following example, a service connection for a REST service that returns contact information (contactsapi) lists three servers that host the REST service. The development server uses the base configuration application profile while the test and production servers use the corresponding application profiles.

Description of vb-app-profiles-server.png follows
Description of the illustration vb-app-profiles-server.png