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 ofutil
. -
domain
: The applicable domain for Cloud applications. For example, the production domain typically uses the domain nameprod
. -
appName
: The Cloud application name. For example, Oracle Utilities Customer Cloud Service uses the application nameccs
. -
context
: A path in the server URI that you designate, such asouaf
to represent Oracle Utilities Application Framework. -
ownerURLComponent
: To determine this component, review theF1-RESTOwnerURIComponent
Extendable Lookup value in your application and refer to the URI Component value. For example, C1 (Customer Care and Billing) uses a value of/customer
.. -
resourceCategoryURLComponent
: To determine this component, review theF1-RESTResourceCategory
Extended Lookup in your application and refer to the URI Component value. For example,C1-INTERACTIONS
(Interactions) uses a value of/interactions
. -
iwsURLComponent
: To determine this component, review the path information for the REST API endpoint within this documentation. For example, the Get Customer Contact API endpoint uses customerContacts/{customerContactId} to access the specific endpoint, with the customerContactId paramter acting as an identifier for the customer contact record.
Authentication
-
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:-
Generate a self-signed certificate.
-
Import the certificate to the Oracle Cloud Infrastructure Identity and Access Management server.
-
Generate the user and client JWT assertions, and sign them with the private key.
-
Specify the
jwt-bearer
grant type and include the generated user and client JWT tokens in the token request call. -
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 C1-INTG-SUITE-API
for the Customer Contacts 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 structure of the Customer Contacts 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/ccs/rest/apis/customer/interactions/customerContacts/{customerContactId}
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.