Quick Start
You can make many types of HTTP requests using the Customer Experience for Utilities REST APIs. You can easily make requests to view, create, update, or delete records as supported in the Customer Experience for Utilities solution. The following is an example of sending a simple REST HTTP request to retrieve a list of the ServiceType reference types. You can find both cURL and Postman steps for this task in this topic.
Consider Before You Start
Review the basics. If you're new to REST APIs, make sure you understand the basics of REST and JSON.
Choose a REST client. REST APIs connect software programs over the HTTP protocol. You need a software client to send the HTTP requests. In the examples, cURL and Postman are used. Additional REST clients are available.
Get Your Oracle CX for Industries Account Info
-
CXIF Server URL. Typically, the CX Industry Framework URL of your Oracle Cloud service. For example,
https://servername.oci.customer-oci.com. -
User name and password. An Oracle Cloud service user with permissions to access the CXIF resources you are using.
You can find the REST Server URL, user name, and password in the welcome email sent to your Oracle Cloud service administrator.
Configure Your Client
With the information gathered so far, you are ready to configure your client to send a REST HTTP request.
-
Construct the request URL. The URL consists of the server name and the resource path:
https://<CXIF-server>/<resource-path>
The <CXIF-server> is the REST Server URL from the previous step, as in:
https://servername.oci.customer-oci.com
The <resource-path> is the relative path or endpoint to the resource you're working with. You can pick any endpoint in All REST Endpoints.
/api/utilitiesAdmin/{version}/{entityName}/{id}Combine the REST Server URL and the resource path, in this example, to get your complete request URL. For more information, see REST API Versions and URL Paths.
https://<CXIF-server>/api/utilitiesAdmin/{version}/{entityName}/{id}For Admin REST API, the complete REST Server URL, in this example, for the service types resource is:
https://<CXIF-server>/api/utilitiesAdmin/v1/serviceTypeIn a client, such as Postman, you enter this combined URL in the Request URL field.
Note:
If you are using Visual Builder Studio to access REST APIs, see Create a Service Connection from a Service Specification. To access REST APIs using Oracle Integration Cloud, see Configure the REST Adapter to Consume an External REST API with No Metadata Described in a Document. You can also build your own client to access REST resources. To build a client using the Java programming language, see Accessing REST Resources with the JAX-RS Client API.
In cURL, you can specify the URL using -X command as follows:
curl -H "Authorization: Bearer <Token> -X GET https://<CXIF-server>/api/utilitiesAdmin/v1/serviceType?q=active=false -
Set the media type. Media type defines the structure of the HTTP payloads exchanged between the server and the client. The media type must be set to application json, and you can specify a media type using the header -H command as follows:
-H 'Content-Type: application/json'For any request that has a request body (like POST or PATCH), you must include the Content-Type request header.
When you are done, the complete cURL command is as follows:
curl -H "Authorization: Bearer <Token>" -X GET https://<CXIF-server>/api/utilitiesAdmin/v1/serviceType?q=active=false / -H 'Content-Type: application/json' | json_ppapplication/json
Authenticate and Authorize
Now that you have configured the client with a complete request URL, it is time to authenticate and authorize yourself. Authentication proves that your credentials are genuine, and authorization allows you to apply your access privileges. In the Customer Experience Industries Framework, Oracle Identity Cloud Services (IDCS) provides the authentication details for the various applications that are installed and configured by the provisioning team.
Authentication
- Get the client configuration information from Oracle Identity Cloud Service (IDCS)
- Use the client configuration information in a REST API client, such as Postman, to generate new access token
Get the Client Configuration Information from IDCS
You can use your existing IDCS registered custom client (confidential application) for accessing IDCS or add and activate a new client (confidential application) in IDCS for working with REST APIs through the Industries Framework.
IDCS supports addition and activation of a confidential application (an application accessed by multiple users and hosted in a secure and protected server. The application uses OAuth 2.0. Applications that can protect their OAuth client id and client secret are called confidential applications).
For detailed information on adding a confidential application, configuring your client, authentication, and authorization, see Add a Confidential Application chapter of the Administering Oracle Cloud Identity Service guide.
Generate New Access Token
Now that your client application is registerd with IDCS as a confidential application, you can request an access token to work with the resources.
- Request an authorization code from the authentication server.
- Use the authorization code to obtain the access token.
You can also use a third-party client, such as Postman, to request the access token from Oracle IDCS.
In a third-party REST API client such as Postman, complete the following steps:
- Create a new request.
- In the Authorization tab, select OAuth 2.0 as Authorization Type and in the Configure New Token section, enter the client configuration already captured from IDCS.
Configure New Token Fields Fields Values Callback URL Enter the Redirect URL value collected from IDCS. Auth URL The IDCS URL appended with /oauth2/v1/authorize is used as the AUTH URL. Example: https://<IDCS-server>/oauth2/v1/authorizeAccess Token URL The IDCS URL appended with /oauth2/v1/token is used as the Access Token URL. Example: https://<IDCS-server>//oauth2/v1/tokenClient ID Enter the Client ID value collected from IDCS. Client Secret Enter the Client Secret value collected from IDCS. Scope Enter the Scope value defined in IDCS. State Can be left blank. Token Name Generic name, can be anything. Grant Type Authentication Code. Client Authentication Send as Basic Auth Header. - Click Get New Access Token.
Postman passes on the information to Oracle Identity Cloud Service (IDCS).
- Login to IDCS by providing your user credentials. The login credentials are validated by IDCS and control is passed back to Postman.
- After the successful authentication, the GET NEW ACCESS TOKEN screen is displayed for 5 seconds. You can wait until the time lapses or click Proceed to navigate to the MANAGE ACCESS TOKENS screen.
- Once the token is generated, make sure that you click on Use Token button in the MANAGE ACCESS TOKENS window. The Access Token gets added to the request.
Note:
The Access Token is valid only until the time period specified in the Application Configuration Setting in IDCS. At the end of the specified time period, the token expires. Click the Get New Access Token button in the Authorization tab of the request to regenerate the Access Token.
Alternatively, you can use the cURL option to pass the token for your Oracle Cloud account, as in this example:
curl -H "Authorization: Bearer Token>" \
-X GET https://<CXIF-server>/api/utilitiesAdmin/v1/serviceType?q=active=true
-H 'Content-Type: application/json'Authorization
- ORA_UER_UTILITIES_KEY_ACCOUNT_ADMINISTRATOR_JOB
- ORA_UER_UTILITIES_CUSTOMER_SERVICE_ADMINISTRATOR_JOB
Send an HTTP Request
Now that your authentication and authorization are set, you are ready to send a test HTTP request. Continuing with our example, you want to get all the information about the structure of the Utilities Common objects in REST. You can do this using the describe action in cURL:
curl -H "Authorization: Bearer <Token>" \
-X GET https://<CXIF-server>/api/utilitiesCommon/v1/describe \
-H 'Content-Type: application/json'If your request for information about the Utilities Common objects is successful, you receive a response with a body similar to the following abbreviated example. If your request fails, and you're using cURL, review the response comments, adjust your request, and then try again. If you're using other clients, review the failure Status Codes, and then try again.
{
"openapi": "3.0.1"
"info": {
"title": "Utilities Search",
"version": "4.0",
"description": "This is Swagger UI environment generated for the Utilities Search Adapter API specification",
"x-vb": {
"serviceType": "openapi",
"transforms": {
"path": "vb/BusinessObjectsTransforms"
}
},
"x-logo": {
"url": ""
}
},
"servers": [
{
"url": "https://servername.oci.customer-oci.com/api"
}
],
"paths": {
"/utilitiesCommon/v1/filter/": {
"get": {
"parameters": [
{
"schema": {
"type": "string"
},
"in": "query",
"name": "context",
"description": "Comma-separated properties to be provided in response",
"required": true
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Data"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Data"
}
}
},
"description": "Success response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Error response"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Error response"
}
},
"operationId": "getFilterList",
"summary": "List the filter for KAM landing/Customer.",
"description": "This operation fetches the list of filter for KAM landing/Customer"
}
},
"/utilitiesCommon/v1/search": {
"post": {
"operationId": "advancedSearch",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "sortBy",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sortOrder",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "context",
"in": "query",
"required": true,
"allowEmptyValue": false,
"schema": {
"enum": [
"customer",
"business"
],
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/advancedSearchRequest"
}
}
}
},
"responses": {
"default": {
"description": "Default response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/searchResponse"
}
}
}
},
"x-vb": {
"queryParameters": {
"context": "customer"
},
"actionHint": "getMany"
}
},
"x-vb": {
"actionHint": "getMany"
}
}
}
},
"components": {
"schemas": {
"Data": {
"properties": {
"filters": {
"enum": [
"business",
"customer"
],
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"title": "Name of the filter",
"description": "This Filter can be used to returns CIS details of the matching Business Customer",
"type": "string"
},
"label": {
"title": "Filter label",
"description": "This Filter can be used to returns CIS details of the matching Business Customer",
"type": "string"
},
"category": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"title": "Name of the filter",
"description": "This Filter can be used to returns CIS details of the matching Business Customer.",
"type": "string"
},
"label": {
"title": "Filter label",
"description": "This Filter can be used to returns CIS details of the matching Business Customer",
"type": "string"
}
}
}
}
}
}
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"description": "Application relevant detail, defined in the API or a common\n list.",
"type": "string"
},
"message": {
"description": "More details and corrective actions related to the error which\n can be shown to a client user.",
"type": "string"
},
"status": {
"description": "HTTP Error code extension",
"type": "string"
},
"referenceError": {
"format": "uri",
"description": "URI of documentation describing the error.",
"type": "string"
}
}
},
"advancedSearchRequest": {
"type": "object",
"properties": {
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
},
"category": {
"nullable": true
}
}
}
}
}
},
"kamSearchResponseRef": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"primaryContactName": {
"type": "string"
},
"lastUpdateDate": {
"type": "string"
},
"groupBy": {
"type": "string"
},
"creationDate": {
"type": "string"
},
"industryCode": {
"type": "string"
},
"favoriteAccountFlag": {
"type": "string"
},
"formattedAddress": {
"type": "string"
},
"partyName": {
"type": "string"
},
"partyUniqueName": {
"type": "string"
},
"primaryContactPartyNumber": {
"type": "string"
},
"partyId": {
"type": "string"
},
"partyNumber": {
"type": "string"
},
"primaryContactPartyId": {
"type": "string"
},
"personId": {
"type": "string"
}
}
}
}
}
},
"customerListSearchResponseRef": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"primaryPhone": {
"type": "string"
},
"customerType": {
"type": "string"
},
"address": {
"type": "string"
},
"partyNumber": {
"type": "string"
},
"primaryIdentifier": {
"type": "string"
},
"accountNumber": {
"type": "string"
},
"partyId": {
"type": "string"
},
"customerName": {
"type": "string"
},
"primaryEmail": {
"type": "string"
},
"cisDivision": {
"type": "string"
}
}
}
}
}
},
"commonSearchResponse": {
"type": "object",
"properties": {
"totalResults": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"count": {
"type": "integer"
},
"hasMore": {
"type": "boolean"
},
"appliedFilters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
},
"category": {
"nullable": true
}
}
}
}
}
},
"searchResponse": {
"allOf": [
{
"$ref": "#/components/schemas/kamSearchResponseRef"
},
{
"$ref": "#/components/schemas/customerListSearchResponseRef"
},
{
"$ref": "#/components/schemas/commonSearchResponse"
}
]
}
}
}
}In a client such as Postman, the results are formatted and displayed in the Response section. For example, Postman lets you view the output in multiple formats.
Now you are ready to do more with your REST APIs. Join the Oracle Developer Community, where you can share tips and advice with others.