Understanding Remote Servers

Create a Remote Server object to store REST Data Source server information.

See Also: Managing REST Data Sources

About Remote Servers

Create a Remote Server object to store REST Data Source server information.

Oracle APEX stores REST Data Source server information (for example, REST APIs) as a Remote Server object. Remote Servers can be shared among multiple REST Data Sources. Changing Remote Server properties affects all REST Sources referencing that object. For example, you can change a Remote Server’s Base URL to move all associated REST Sources from a test to a production system. Since Remote Servers are stored at the workspace-level, Remote Servers are visible in all applications in a workspace.

When you create a Remote Server you select one of the following Sever Types:

REST Data Source - A Remote Server for consuming a remote REST API.
Authentication - A Remote Server used for authentication.
Print Server - A Remote Server for an external print server. You can create a Print Server in your workspace and use it in an application. By default, the print server configuration at instance level is used.
File Server - A Remote Server for remote file storage.

How APEX Stores REST Data Source Information

Learn how Oracle APEX stores REST Data Source information.

Oracle APEX splits the endpoint URL of a REST Data Source into two parts. The first part is the server-specific part and is stored as a separate entity called the Remote Server. You can reuse a Remote Server with multiple REST Data Sources if each one uses the same server, port, and URL Path Prefix (context root). Remote Servers are stored at the workspace-level and therefore visible in all applications.

The second part of the endpoint URL and is specific to the REST Data Source. Multiple REST Data Sources can share one Remote Server, thus sharing information such as the Base URL and Authentication. If you change Remote Server attributes, the change impacts all REST Data Sources using the Remote Server. Remote Servers make it easy to move a collection of REST Data Source. For example, you can move from a test system to a production system by changing the URL within the Remote Server object.

About Flexible Remote Servers

A Flexible Remote Server enables you to populate the server portion of the Endpoint URL dynamically using a callback procedure you specify in the Configuration Procedure attribute.

Flexible Remote Server works as follows:

When the REST Data Source is invoked, the APEX Engine evaluates the Remote Server, Configuration Procedure attribute.
If the Configuration Procedure attribute has a value, either stored in the database or in an anonymous block in the PL/SQL Code attribute, the APEX Engine executes the procedure to fetch a collection of substitution parameters that are then used to change the Endpoint URL.

Flexible Remote Server Use Cases

Common use cases for using a Flexible Remote Server include:

Environment dependencies - A Flexible Remote Server is a good choice when the environment is dependent upon where the server or application is deployed (for example, in production, test or development instances). Instead of manually changing the Endpoint URL attribute on the Edit Remote Server page for each environment, you can use an API to change it dynamically.

Tip: You can also use APPLICATION_ADMIN.SET_REMOTE_SERVER procedure to change the Endpoint URL in a deployment script. See SET_REMOTE_SERVER Procedure in Oracle APEX API Reference
Application data or the application user dependencies - A Flexible Remote Server enables you to use the Configuration Procedure attribute to change the Endpoint URL at runtime depending on dynamic parameters. These dynamic parameters are flexible and can be based on a configuration table, items in Session State, Application Items or Substitution Items.

The results of the Configuration Procedure are cached and reused within the same request (page view or page processing).

Note: Flexible Remote Servers are only supported for REST Data Source and Authentication Server Types or Remote Servers used in REST Enabled SQL.

Configuring a Flexible Remote Server

To configure a Flexible Remote Server, edit the Remote Server and enter a procedure name in the Configuration Procedure attribute. This procedure can be the name of a procedure stored in the database, stored in a database package procedure, or a procedure stored in the PL/SQL Code attribute.

This signature of the procedure must have two parameters of type:

p_info in apex_plugin.t_remote_server_info
p_config in out apex_plugin.t_remote_server_config

The parameter p_config has two optional attributes which can be changed in the configuration procedure:

p_config.base_url - base_url changes the Endpoint URL.
p_config.substitutions - substitutions assigns name/value pairs using apex_t_varchar2. Oracle APEX substitutes each #NAME# in the base url or Endpoint URL.

Together these two attributes determine the actual Endpoint URL the Remote Server uses.

Tip: To view Configuration Procedure examples, see item Help for the Configuration Procedure attribute.

The following example changes the base URL if the application ID is 100:

procedure my_server_config(
  p_info    in  apex_plugin.t_remote_server_info,
  p_config  out apex_plugin.t_remote_server_config )
is
begin
  if v('APP_ID') = 100 then
    p_config.base_url := 'https://app100.example.com';
  else
    p_config.base_url := 'https://example.com';
  end if;
end;

You can also can use placeholders by enclosing the “name” with the number symbol (#) and use substitutions to replace the value in those placeholders. Consider the following example:

procedure my_server_config(
  p_info in apex_plugin.t_remote_server_info,
  p_config out apex_plugin.t_remote_server_config )
is
begin
  p_config.base_url := 'https://app#app_id#.example.com/#tenant#';
  p_config.substitutions := apex_t_varchar2();
  apex_string.plist_put( p_config.substitutions, 'app_id', v('APP_ID') );
  apex_string.plist_put( p_config.substitutions, 'tenant', v('TENANT') );
end;

See Also:

Exporting and Importing Remote Server Information

Learn about exporting and importing Remote Server information.

When you export an application, referenced Remote Servers are added to the export file. When you import the application into another workspace, APEX checks whether the target workspace already contains Remote Servers with the same static ID. If a Remote Server already exists, the application uses it. Otherwise the Remote Servers from the import file are created in the target workspace.