17.4.2 Creating a REST Data Source

Create a REST Data Source from Shared Components.

To create a REST Data Source:

  1. Navigate to the REST Data Sources page:
    1. On the Workspace home page, click App Builder.
    2. Select an application.
    3. On the Application home page, click Shared Components in the center of the page.
    4. Under Data Sources, select REST Data Sources.
  2. On the REST Data Sources page, click Create.
  3. Method - Select From Scratch and click Next.


    If you select As copy of an existing REST Data Source, select the application to copy from and follow the on-screen instructions.
  4. General:
    1. REST Data Source Type - Determines the REST Data Source type, which is either a built-in type or a type defined by a REST Source Plug-In. Available built-in REST Data Sources types include:
      • Simple HTTP - Select this option for a simple HTTP data feed. Oracle APEX assumes that all data is returned with the first request and that the server does not support server-side filtering, ordering, or other advanced REST service feature. All invocation details and parameters must be configured manually.

      • Oracle REST Data Services - Denotes Oracle REST Data Services (ORDS). These REST services follow the Oracle REST standard, which means that GET, POST, PUT, or DELETE operations are standardized. Server-side filtering and ordering are supported. Oracle APEX can leverage these features by delegating report order-bys and filters to the REST service.

      • REST Enabled SQL Query - Denotes a REST Source on top of a SQL Query executed on a REST Enabled SQL Reference. Oracle APEX supports filtering and pagination, but no DML on these endpoints.

      • Oracle Cloud Applications (SaaS) REST Service - Denotes RESTful web services provided by Oracle Cloud SaaS Applications. Use this web service type to integrate Oracle SaaS REST Services into your Oracle APEX application. Oracle Oracle APEX pagination for these services.

      • Oracle Cloud Infrastructure (OCI) REST Service - Denotes RESTful web services provided by Oracle Cloud Infrastructure. Use this web service type to integrate OCI REST Services (for example, accessing the Object Store) into your Oracle APEX application. Oracle APEX supports pagination for these Services.

      The REST Data Source Type determines what appears next. In the example, REST Data Source Type is set to Simple HTTP.

    2. Name - Enter a descriptive name for this REST Data Source.
    3. URL Endpoint - Enter the Endpoint URL (starting with http:// or https://) for this REST Data Source.


      Do not add query string parameters by appending ?name1=value&name2=value. These are configured on the Advanced wizard page after you configure Authentication.

    4. HTTPS Host Name - The host name to be matched against the common name (CN) of the remote server's certificate for an HTTPS request. It can also be a domain name like *.example.com. If NULL, the host name in the given URL is used.
    5. Click Next.
  5. Remote Server:
    1. Remote Server - Choose an existing Remote Server object. The HTTP Endpoint URL of a REST Data Source consists of the remote server (Base URL) and the service specific part. Remote Servers are stored as separate Entities. When multiple REST Data Sources share the same remote server, they can easily be redirected to another physical location (for example, from test to production) by just changing the base URL within the Remote Server definition..
    2. Base URL - This is the Base URL of the chosen Remote Server object. The HTTP Endpoint URL of this REST Data Source is made up from the Base URL and the service-specific path suffix below.

      For example:

      • http://api.example.com:8080/myservices/test/

      • https://api.example.com/ords/scott/

    3. Service URL Path - Enter the service-specific URL Path for this REST Data Source. The HTTP Endpoint URL is built by appending this to the Base URL specified in the Remote Server object.

      For example:

      • /services/customers/

      • /products/4711/details

    4. Click Next.
  6. If REST Data Source Type is Simple HTTP, under Settings, Pagination Type, select one of the following:
    • Page Size and Fetch Offset - Flexible pagination where the REST API allows the request a specific set of rows, using page size and offset ("start at row") parameters.

      The following shows typical URL. In this example, the URL requests page number 2 with a page size of 100, which leads to rows 101 to 200 being returned.


      In the previous example, note that the parameters named limit and offset can be arbitrary and depend upon the REST API being used.

    • Page Size and Page Number - Pagination where the REST API allows the request a set of rows, using page size and page number parameters.

      URLs typically look like the following example which requests page number 2 with a page size of 100, which leads to rows 101 to 200 being returned.

    • http://hostname.domain.com/path/to/rest_api?size=100&page=2
    • Page Number - Pagination where the REST API allows to request a set of rows, using a page parameter. The Page Size is fixed and determined by the REST API.

      URLs typically look like the following example which requests page number 2. If the REST API uses a fixed page size of 20, rows 21 to 40 will be returned.


    The UI changes based on Pagination Type you select. See field-level Help for more information on specific attributes.

  7. Authentication Required - Choose whether the new REST Data Source requires Authentication.
  8. To proceed, select one of the following:
    • Create REST Source Manually - This option does not include Discovery mode. Based on the previously entered information, a REST Data Source is created with a few sample operations and a sample data profile. This option creates an incomplete REST Data Source that is unusable with an APEX component. To correctly reflect the external web service, you will need to edit the operations and the data profile.
    • Advanced - Presents advanced parameters for the Data Profile. Use Response Sample to upload a sample JSON (or XML) response. Once a file is uploaded, APEX performs a Data Profile Discovery on the uploaded file.
    • Discover - Starts Discovery mode. APEX executes multiple HTTP requests in order to get information about the external Web service. APEX samples the data (JSON or XML) returned by the Web service and derives a Data Profile (consisting of metadata about the JSON attributes). Discovery results then display and confirms whether to create the REST Data Source.
  9. If you click Advanced, the Parameter page appears.
    Use the Parameters page to configure initial REST Data Source parameters which might be required for discovery. Some REST Data Sources may require you set specific HTTP Headers (for example, User-Agent). After setting advanced parameters, select either Create REST Source Manually or Discover.
  10. If you select Discover, APEX invokes the REST service URL and a Preview appears. From the JSON response, APEX derives attributes and their data types and uses this to create a Data Profile.

    The information that displays depends upon the complexity of the target service. For simple HTTP services or ORDS services which do not provide metadata about their JSON response attributes, APEX investigates the JSON or XML response, samples the data, and creates a proposal for a data profile. The Data tab displays the sample response data, formatted as a report.

    The columns tab shows information about the data profile columns APEX has found during discovery. Use this tab to verify whether the column data types are correct.

    Click Server Response to view additional detailed information about the REST Data Source response, such as the response body, response headers and the REST Data Source operations.

  11. Click Create REST Data Source.
    The REST Data Source is created.