1. REST API for Oracle Utilities Digital Asset ManagementOracle Utilities REST API for Digital Asset
  2. Establishing a Connection

Establishing a Connection

REST APIs connect software programs over the HTTP protocol, typically using JSON. A software client to send the HTTP requests is required to send requests to the application server. To make an HTTP request to a REST API endpoint, you need to establish your connection to the application REST servlet using the following requirements:

  • Request URL: The URL of your Oracle Utilities product along with the path for the REST API endpoint. For example: https://{host}:{port}/{context}/rest/apis/{ownerURLComponent}/{resourceCategoryURLComponent}/{iwsURLComponent}. Information on constructing the full request URL is provided below.

  • Authentication: Access to the REST API endpoints requires the proper authentication, which includes an Oracle Cloud or Oracle Utilities product user name and password with proper authorization privileges.

Constructing the Request URL

All interaction is done as a series of HTTP requests against given Uniform Resource Identifiers (URI). A URI is a string of characters that uniquely identifies a particular resource. A RESTful Inbound Web Services (IWS) in the Oracle Utilities product can have multiple reference endpoints to access the full or partial resource and multiple operations to perform for each endpoint.

An endpoint URL points to a unique Inbound Web Service Name and Operation Name combination within the Oracle Utilities application that determines the HTTP method and URL to the system resource.

The REST endpoint URL is obtained from the API Specification from the computed URL and the URI component. The endpoint URL follows this format:

{computedURL}/{iwsOperationURLComponent}

Where:

  • computedURL: The base URL referring to the common path for the API. The value is obtained from the REST API Specification of the REST IWS within the Oracle Utilities product application.
  • iwsOperationURLComponent: The reference to a URI component. The value is obtained from the URI Component of the IWS - Operations Collection.

The computedURL is the base URL used by the endpoints. A part of this URL is populated in a system variable which includes the URL through the ../apis/ components, with the remaining iwsOperationURLComponent part of the URL derived by the application. On Premise applications use the system variable F1_REST_BASE_URL and Cloud applications use the system variable CLOUD_F1_REST_BASE_URL. These system variables support the difference between an On Premise and Cloud formats for the computedURL.

  • Cloud Applications:

    https://{host}/{tenant}/{domain}/{appName}/rest/apis/{ownerURLComponent}/{resourceCategoryURLComponent}/{iwsURLComponent}

  • On Premise Applications: https://{host}:{port}/{context}/rest/apis/{ownerURLComponent}/{resourceCategoryURLComponent}/{iwsURLComponent}

To create the full URL, refer to the additional details on each component:

  • host: The host name or IP address for the system hosting the resource.

  • port: The port number of the system hosting the resource. This component is only required for On Premise Applications.

  • tenant: The code for your utility company that is provisioned by Oracle. This documentation uses an example of util.

  • domain: The applicable domain for Cloud applications. For example, the production domain typically uses the domain name prod.

  • appName: The Cloud application name. For example, Oracle Utilities Digital Asset Cloud Service uses the application name dac.

  • context: A path in the server URI that you designate, such as ouaf to represent Oracle Utilities Application Framework.

  • ownerURLComponent: To determine this component, review the F1-RESTOwnerURIComponent Extendable Lookup value in your application and refer to the URI Component value. For example, X1 (Customer to Meter and ODM) uses a value of /cross.

  • resourceCategoryURLComponent: To determine this component, review the F1-RESTResourceCategory Extended Lookup in your application and refer to the URI Component value. For example, X1-DIGITALASSETS uses a value of/digitalAssets.

  • iwsURLComponent: To determine this component, review the path information for the REST API endpoint within this documentation. For example, the Create Program Enrollments API endpoint uses /programEnrollments/enroll to access the specific endpoint.

Authentication

The web service component of the product is hosted in the JEE Web Application Server and utilizes web services security mechanism that are supported by that server. Security policies include:

  • The JEE Web Application Server allows security policies or security access rules to be configured for an individual Inbound Web Service. Any of the valid policies and security rules supported by the JEE Web Application Server can be used.

  • Web service management products such as Oracle Web Services Manager (OWSM) can be used to augment security for Inbound Web Services within On Premise installations.

    The Oracle Security default policy (Wssp1.2-2007-Https-BasicAuth.xml), which extracts the user name and password credentials from the HTTP header, is used if no default is specified in any facility or on any Inbound Web Service.

The following authentication options are support for Cloud applications, you must submit the user name and password for your Oracle Cloud account.

  • Basic Authentication: This authentication method requires a username and password. All calls are made over SSL, which is a standard security technology for establishing an encrypted link between a server and a client. This ensures that the user credentials in the request are kept secure during transport.

  • OAuth Authentication: This authentication method is useful when Basic Authentication does not provide sufficient security. This authentication method requires the following information:

    • Access Token URI: The OAuth server URL from which to obtain the access token.
    • Client ID: The client identifier issued to the client during the registration process of the application with the Oracle Cloud Infrastructure Identity and Access Management server.
    • Client Secret: The client secret issued to the client during the registration process of the application with the Oracle Cloud Infrastructure Identity and Access Management server.
    • Username: The resource owner's username, or also referred to as the application username.
    • Password: The resource owner's password, or also referred to as the application user password.

    Client administrators can retrieve the Client ID and Client Secret from the Oracle Cloud Infrastructure Identity and Access Management console. Separate Oracle Cloud Infrastructure Identity and Access Management OAuth clients can be created and their secrets can be regularly rotated as needed to maintain a secure environment.

  • JSON Web Token (JWT) Authentication:

    This authentication method can be considered as the most secure option because it does not require sharing of secrets or passwords. It relies on a trusted Oracle Cloud Infrastructure Identity and Access Management application, with an imported certificate, where the user and client tokens must be digitally signed. To implement this type of authentication using a self-signed user and client assertion, an external party must perform the following:

    1. Generate a self-signed certificate.

    2. Import the certificate to the Oracle Cloud Infrastructure Identity and Access Management server.

    3. Generate the user and client JWT assertions, and sign them with the private key.

    4. Specify the jwt-bearer grant type and include the generated user and client JWT tokens in the token request call.

    5. Use the returned access token to invoke the Oracle Utilities REST API endpoint.

Authorization

Once a user is identified and verified by the application server, the user that is supplied must be authorized for access to the requested functions and data within the application. For example, users are granted access to application services, such as for W1-ACT for the Work Activity Maintenance Object, through user groups such as ALL_SERVICES. An application service may include available actions, typically Add, Change, Delete, and Inquire. These actions are available for objects which can be accessed using the online or batch application or are also exposed as RESTful resources through Inbound Web Services. The Inbound Web Services component of the application uses the same authorization model as the online user and batch components. System users and user groups can be configured to support integrations.

Note:

For additional details, including a list of specific roles for accessing a REST resource, refer to The Big Picture of Application Security section in your Oracle Utilities product Administrative User documentation.

Sending Requests

With the request URL and the proper authentication you can send a test HTTPS request. For example, to retrieve all of the information about the Service Point object, you can perform the following GET action using cURL for a Cloud environment: 

curl -u {username}:{password} -X GET -H "Accept:application/json"
                https://{host}/{tenant}/dev01/dac/rest/apis/cross/v-model/servicePoints/{servicePointId}

Note:

To review the available actions for REST APIs, refer to Supported Methods.

If your response fails while using cURL, you can review the response comments and attempt to fix any errors in your request. If you are using another REST client, review the failure status code details within the API endpoint specifications and use the information to attempt to fix any errors in your request.