Inbound Web Services
In Oracle Utilities cloud services, inbound web services do not need to be deployed to be accessible. Once an inbound web service is set to active, it is ready to be used and accessed.
Oracle Utilities cloud services support both SOAP and REST services. Implementations can create custom inbound web services but no XSLs can be referenced by the inbound web service.
SOAP Inbound Web Services
This section provides information related to SOAP-based inbound web services.
Accessing a Web Service WSDL on Cloud
You can access and view the WSDL (Web Service Definition Language) of a SOAP service through the cloud service application or by executing a curl command. The WSDL file contains the structure, the schema and security specification for the desired web service.
All WSDLs are secured in Oracle Utilities cloud services. The WSDL URL must include some form of authentication to be accessed, such as a basic username and password.
Users cannot access the WSDL by providing the WSDL URL from a browser or from SOAPUI or any web service testing application. They must use the cloud service application or a curl command.
Cloud Service Application:
Use the following procedure to access a web service WSDL using an Oracle Utilities cloud service application:
1. Select Admin, then Integration, then Inbound Web Service, and then Search to access the Inbound Web Service Query portal.
2. Search for the SOAP service you wish to access (select "SOAP" from the Web Service Class drop-down list)
3. Once the SOAP web service is displayed in the Inbound Web Service portal, click the WSDL link in the View WSDL field.
Curl Command:
Use the following procedure to access a web service WSDL using a curl command:
The curl command format:
curl -k -X GET https://{host}:{port}/{tenant}/{domain}/{appName}/soap/api/iws/{IWSServiceName}?WSDL -u username:password
where:
https://{host}:{port}/{tenant}/{domain}/{appName} | Product Application URL Example of Customer Cloud Service Application URL: https://cloudenv:port/tenant/prod/ccs |
|---|---|
/soap/api/iws/ | Fixed text part of the URL |
IWSServiceName | SOAP Inbound Web Service Name |
username | User name to login to the application |
password | Password to login to the application |
Getting the Endpoint URL on Cloud
You can obtain the endpoint URL for a SOAP service from the WSDL. Go to the service name part of the WSDL and you get the address location which is the endpoint URL.
The endpoint URL follows this format:
https://{host}:{port}/{tenant}/{domain}/{appName}/soap/api/iws/IWSServiceName
Testing and Using the SOAP Inbound Web Service
There are several resources to use when testing SOAP-based inbound web services.
This is an example of using SOAPUI to test an inbound web service.
1. Access the secured WSDL from the cloud service application or by executing the curl command as described above.
2. Save the WSDL file locally.
3. Create a new SOAP project using the saved local WSDL.
4. Provide the necessary information in the request message.
5. Provide basic authorization information.
• Select "Basic" from the Authorization drop-down list.
• Enter appropriate values in the Username and Password fields.
• Select the Authenticate pre-emptively option.
6. Test the service as appropriate to your requirements.
REST Inbound Web Services
This section provides information related to REST-based inbound web services.
Accessing REST API Specification
REST API specifications define or describe the reference endpoints in an API. You can access and view the API Specification of a REST inbound web service through the utilities cloud application or by making a REST call.
Cloud Service Application:
Use the following procedure to access a REST API specification using an Oracle Utilities cloud service application:
1. Select Admin, then Integration, then Inbound Web Service, and then Search to access the Inbound Web Service Query portal.
2. Search for the REST service you wish to access (select "REST" from the Web Service Class drop-down list)
3. Once the REST web service is displayed in the Inbound Web Service portal, click the View Specification link in the API Specification field.
REST Call - Cloud Service:
Use the following procedure to access a REST API specification using a REST call with a cloud service:
The endpoint URL to use to make the REST call uses the following format:
https://{host}:{port}/{tenant}/{domain}/{appName}/rest/openapi/{IWSServiceName}
The endpoint URL to use to make the REST call to get a v2 Swagger Specification follows this format:
https://{host}:{port}/{tenant}/{domain}/{appName}/rest/openapi/v2/{IWSServiceName}
When making the REST call, use the Get method. Refer to the sample URL below.
Method: GET
URL: https://host:port/tenant/domain/appName/rest/ouaf/openapi/F1-GetIWSWSDL
REST Call - On-Premises Application:
Use the following procedure to access a REST API specification using a REST call with a on-premises application:
The endpoint URL to use to make the REST call to get an Open API Specification follows this format:
https://{host}:{port}/{context}/rest/ouaf/openapi/{IWSServiceName}
The endpoint URL to use to make the REST call to get a v2 Swagger Specification follows this format:
https://{host}:{port}/{context}/rest/ouaf/openapi/v2/{IWSServiceName}
When making the REST call, use the Get method. Refer to the sample URL below.
Method: GET
URL: https://host:port/ouaf/rest/ouaf/openapi/v2/F1-GetIWSWSDL
Getting the Endpoint URL
A REST inbound web service can have multiple reference endpoints to access the resource and multiple methods for each endpoint. An endpoint URL points to a unique inbound web service name and an Operation name and shows the whole path to the resource.
The REST endpoint URL is obtained from the API Specification. It is a combination of the Computed URL and the URI Component.
The endpoint URL follows this format:
{ComputedURL}/{iwsOperationURLComponent}
where:
ComputedURL | Base URL referring to the common path for the API. The value is obtained from the REST API Specification of the REST inbound web service. |
|---|---|
iwsOperationURLComponent | Reference a URI Component. The value is obtained from the REST API Specification -Method and URI collection or in the URI Component of the Inbound Web Service - Operations Collection. |
Example:
The w1WorkActivity REST inbound web service API Specification has two resource URI Components:
The endpoint URLs for this service are:
https://{hostname}:{port}/{tenant}/dev01/wacs/rest/apis/asset/work/workActivity/{activityId}
https://{hostname}:{port}/{tenant}/dev01/wacs/rest/apis/asset/work/workActivity/scheduleWindow/{activityId}
About the Computed URL
The Computed URL is the base URL used by the endpoints. A part of the URL is populated in a System Variable called F1_REST_BASE_URL. The F1_REST_BASE_URL system variable would only contain the configuration up to the 'apis' portion of the URL, and the remaining components of the URL would be derived by the application. The system variable supports the difference between formats used with on-premises applications and cloud services.
The Computed URL follows the format below:
For Cloud Applications:
https://{host}:{port}/{tenant}/{domain}/{appName}/rest/apis/{ownerURLComponent}/{resourceCategoryURLComponent}/{iwsURLComponent}
For On-Premises Applications:
https://{host}:{port}/{context}/rest/apis/{ownerURLComponent}/{resourceCategoryURLComponent}/{ iwsURLComponent}
where:
https://{host}:{port}/{tenant}/{domain}/{appName} | Cloud Product Application URL Example of Customer Cloud Service Application URL: https://cloudenv:port/tenant/prod/ccs |
|---|---|
https://{host}:{port}/{context} | On-Premises Application URL Example of Customer Care and Billing Application URL: https://hostname:port/ouaf |
/rest/apis | Fixed text part of the URL |
ownerURLComponent | The value is obtained from URI COMPONENT in Owner Configuration for REST services extendable lookup (F1-RESTOwnerURLComponent) where there is an entry for each owner flag. Examples: F1 (Framework): /common C1 (Customer): /customer |
resourceCategoryURLComponent | The value is obtained from URI COMPONENT in Resource Category for REST services extendable lookup (F1-RESTResourceCategory) where there is an entry for each resource category. Example: F1-SYSTEM (System): /system |
Note: The Computed URL for cloud applications may not always be the same as the application URL. Always get the value from the API Specification of the REST Service.
Methods and Parameters
REST inbound web services support the following HTTP Methods:
• Get
• Patch
• Post
• Put
The method is defined in the HTTP Method drop-down list in the Operations section of the Inbound Web Service portal.
For the Get, Put and Patch HTTP Methods, "Query" or "Path" parameters can be passed with the endpoint. This is specified using the Parameter Type drop-down list in the Parameters columns in the Operations section of the Inbound Web Service portal
• Path parameters: These are parameters that are part of the endpoint and are required. Usually they are represented in the endpoint with curly braces.
• Query parameters: These parameters are often optional. They are not part of the endpoint but rather are included in the endpoint URL after a question mark, followed by name value pairs.
Example:
'../getAccountBills/{accountId}?startDate=20190101&endDate=20190630'.
Testing and Using the REST Inbound Web Service
There are several resources to use when testing REST inbound web services.
This is an example of using POSTMAN to test an inbound web service.
1. Go to the REST API Specification to get the endpoint URL and the HTTP Method for the web service you wish to test.
2. Open POSTMAN and populate the necessary information.
a. Provide the HTTP Methods and the Request URL
b. On the Authorization tab, choose "Basic Auth Type" and provide the user name and password
c. On the Header tab, provide the following key value pair to send and accept json messages.
Key | Value | Description |
|---|---|---|
Accept | application/json | Indicate the response media type that is acceptable |
Content-Type | application/json | Indicate the media type of the resource. To send and accept xml messages change the value to "application/xml". |
d. On the Body tab, provide the request message. Sample request and response messages can also be found on the REST API Specification by expanding each resource URI.