This chapter describes how to use the Oracle Communications Evolved Communications Application Server (OCECAS) RESTful APIs to create and access service data.
For a complete description of the OCECAS RESTful API, see Oracle Communications Evolved Communications Application Server SDC RESTful API Reference.
You can create and access OCECAS service data by using HTTP RESTful API commands.
Note:
You must first log in to the Management domain (see "Logging In to the Management Domain") before you can use the other API commands.This section provides examples for performing the following operations on the OCECAS Management domain:
To log in to the OCECAS Management domain, issue a POST command like the one in the following example, replacing hostname and port with the host name and port number of the management domain server. Replace the encoded authorization code with the encoded authorization code for your username and password:
POST /api/session HTTP/1.1 Host: hostname:port Authorization: Basic dXNlcjp1c2VyNHNkYw== Cache-Control: no-cache
The response indicates the outcome of the login attempt.
You can create a script to obtain the encoded authorization pass code. For example, the following steps create a Python script to obtain the encoded authorization pass code and execute the script to display it.
Create Python script called pass.py using the following commands, replacing name and password with an actual username and password.
cat pass.py import base64 username="name"; password="password" base64string = base64.encodestring('%s:%s' % (username, password)).replace('\n', '') print base64string
Enter the following command to display the pass code:
python pass.py
A Cross Site Request Forgery (CSRF) token is used to prevent cross site request forgeries. A CSRF token is required in all PUT and POST operations in the service-related RESTful APIs.
To obtain a CSRF token, issue the following GET command after logging into the management domain. Replace hostname and port with the host name and port number of the OCECAS management domain:
GET /api/session HTTP/1.1 Host: hostname:port Authorization: Basic dXNlcjp1c2VyNHNkYw== Cache-Control: no-cache
The CSRF token is returned in the response:
{
"name": "user",
"fullName": "user",
"userSession": {
"name": null,
"attributes": [
{
"key": "csrfToken",
"value": "2c3890b3bb4431a1b47465fbfc58a7d6830c3dbf03b80630767b44225c184ae5"
},
Note:
You must submit the CSRF token for all POST and PUT commands in service-related APIs. Otherwise you will receive a '403 Forbidden' error.For a description of the CSRF token and information on how to obtain it, see "Obtaining a CSRF Token".
You can submit the CSRF token in a POST or PUT command either in an X-ORA-OCECAS-csrfToken header, as shown here, or in attached JSON content.
POST /api/pipelines/pipe/environments/env/deployments/ HTTP/1.1 Host: hostname:port Content-Type: application/json X-ORA-OCECAS-csrfToken: 2c3890b3bb4431a1b47465fbfc58a7d6830c3dbf03b80630767b44225c184ae5 Cache-Control: no-cache
Submit the CSRF token in JSON content as shown in the following example:
POST /api/pipelines/pipe/environments/env/deployments/ HTTP/1.1 Host: hostname:port Content-Type: application/json Cache-Control: no-cache
Content:
{
"csrfToken": 2c3890b3bb4431a1b47465fbfc58a7d6830c3dbf03b80630767b44225c184ae5
"name": "Test",
"description": "A new test change set"
}
To create a change set, issue a POST command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain:
POST /api/change-sets HTTP/1.1 Host: hostname:port Content-Type: application/json Cache-Control: no-cache
Attach JSON content like that shown in the following example to specify the name of the change set and a description. Replace the csrfToken value with the value for your authorization credentials. See "Obtaining a CSRF Token" for more information.
{
"csrfToken": 2c3890b3bb4431a1b47465fbfc58a7d6830c3dbf03b80630767b44225c184ae5
"name": "Test",
"description": "A new test change set"
}
To get change-set details, including the change set ID, issue a GET command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain:
GET /api/change-sets HTTP/1.1 Host: hostname:port Cache-Control: no-cache
Returns a changeSets object that contains a list of currently available change sets.
To get a change set, issue a GET command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain, and replacing ChangeSetID with the ID of the target change set. See "Getting Change Set Details" for information about finding a change set ID.
GET /api/change-sets/ChangeSetID HTTP/1.1 Host: hostname:port Cache-Control: no-cache
The response returns a changeSet object for the named change set.
To get a list of differences for a change set, compared with its base change set, issue a GET command like the one in the following example. Replace hostname and port with the host name and port number of the OCECAS management domain, and replace ChangeSetID with the ID of the target change set. See "Getting Change Set Details" for information about finding a change set ID.
GET /api/change-sets/ChangeSetID/diffs HTTP/1.1 Host: hostname:port Cache-Control: no-cache
The response returns the differences for the specified change set, including a list of the control flows and resources that were either added or changed as part of that change set.
To get a list of environment details, including environment IDs, issue a GET command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain:
GET /api/environments HTTP/1.1 Host: hostname:port Cache-Control: no-cache
Returns a list of all environments.
To get a list of all pipelines, including IDs, issue a GET command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain:
GET /api/pipelines HTTP/1.1 Host: hostname:port Cache-Control: no-cache
Returns a list of all pipelines.
To deploy a change set, issue a POST command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain. Replace pipe with the pipeline ID and env with the environment ID in the pipeline to which you want to deploy the change set. See "Getting a List of Pipelines" for information on finding a pipeline ID and "Getting a List of Environments" for information on finding an environment ID.
POST /api/pipelines/pipe/environments/env/deployments/ HTTP/1.1 Host: hostname:port Content-Type: application/json Cache-Control: no-cache
Attach JSON content that describes the deployment object. For example the following lines define the deployment object for the OCECAS "VoLTE, VoWiFi, and eSRVCC" change set. Replace the csrfToken value with the value for your authorization credentials. See "Obtaining a CSRF Token" for more information.
{
"csrfToken": 2c3890b3bb4431a1b47465fbfc58a7d6830c3dbf03b80630767b44225c184ae5,
"id": 41,
"changeSet": {
"csrfToken": null,
"id": 2,
"name": "VoLTE, VoWiFi and eSRVCC",
"description": "VoLTE, VoWiFi and eSRVCC change set",
"serviceProviderId": 1,
"baselineId": 1,
"pipelineId": null,
"creationDate": 1437615562000,
"lastUpdated": 1437615562000,
"deleted": false,
"editable": false,
"inactive": false,
"active": true,
"scheduled": false,
"retracted": false,
"open": false,
"erroredObjects": [],
"username": "VoLTE Installer"
},
"baselineId": 1,
"state": "A",
"creationDate": 1437615744000,
"scheduledDate": 1437615744000,
"lastUpdated": 1437615744000,
"environment": 1,
"productionEnvironment": false,
"pipeline": 1,
"conflictPotential": null,
"active": true,
"scheduled": false,
"editable": true
}
The response returns the deployment object for the specified change set.
To get telemetry records, including the record names, issue a GET command like the one in the following example. Replace hostname and port with the host name and port number of the OCECAS management domain:
GET /api/telemetry/records HTTP/1.1 Host: hostname:port Cache-Control: no-cache
Returns a telemetrys object that contains a list of telemetry records.
To get the details of a telemetry record for a given name, issue a GET command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain, and replacing name with the telemetry name. See "Getting Telemetry Records" for information about finding a telemetry name.
GET /api/telemetry/records/name/name HTTP/1.1 Host: hostname:port Cache-Control: no-cache
The response returns the details of the telemetry record of the given name.
To get statistics definitions for a change set, including the names of statistics, issue a GET command like the one in the following example. Replace hostname and port with the host name and port number of the OCECAS management domain, and replace changeSetID with the ID of the change set for which you want statistics definitions. See "Getting Change Set Details" for information on finding a change set ID.
GET /api/statistics/definitions/changeSetID HTTP/1.1 Host: hostname:port Cache-Control: no-cache
Returns a Statistics object that contains the statistics definitions.
To get statistics, issue a GET command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain, and replacing name with the statistic name. See "Getting Statistics Definitions" for information on finding a statistic name.
GET /api/statistics/records/name/name HTTP/1.1 Host: hostname:port Cache-Control: no-cache
The response returns a statistics object containing all of the statistics records matching the given name.
To get a control flow, issue a GET command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain. Replace changeSetID in the header with the change set ID and name with the name of the control flow. You can obtain the control flow name from the response returned in "Getting Change Set Differences".
All prerequisite configuration data, including service data, external concepts, statistic definitions, EDRs and schemas referenced directly or indirectly by activities of the flow, is included in the exported file.
GET /api/change-sets/changeSetID/access-control-flows/name HTTP/1.1 Host: hostname:port Accept: text/xml Cache-Control: no-cache
The response returns the latest version of the controlFlow instance.
Note:
The export does not include application triggers and the related VoLTE-specific service data that underpins the application view. This information cannot be computed as a prerequisite of any control flow. If a VoLTE installation has been lost or removed, the applications information will be lacking after all flows are reimported. If necessary, you can reinstate this using application trigger and service data REST requests.To update a control flow, issue a PUT command like the one in the following example, replacing hostname and port with the host name and port number of the OCECAS management domain. Replace changeSetID in the header with the change set ID and name with the name of the control flow. Attach JSON content to describe the control flow. See "Importing a Control Flow" for an example of JSON content for a control flow.
PUT /api/change-sets/changeSetID/access-control-flows/name HTTP/1.1 Host: hostname:port Content-Type: text/json Cache-Control: no-cache
To add a control flow, issue a POST command like the one in the following example. Replace hostname and port with the host name and port number of the OCECAS management domain. Replace ChangeSetID with the ID of the target change set and attach JSON content like that shown in the example to describe the control flow:
POST /api/change-sets/ChangeSetID/access-control-flows HTTP/1.1 Host: hostname:port Content-Type: text/json Cache-Control: no-cache
All prerequisite configuration data, including service data, external concepts, statistic definitions, EDRs and schemas referenced directly or indirectly by activities of the control flow, may be included in the imported file and will be used if present.
You might encounter compile issues in cases where a parent control flow is imported before its child control flows are all imported. The parent will report that one or more linked control flows cannot be found. To resolve this issue, continue importing the child flows until all are present. Then reimport the parent, which requires a PUT operation because the parent already exists.
It should not be necessary to manually edit any imported control flow. A reimport might be necessary in the case where a child was initially lacking, because the linked control flow name is not saved in the parent control flow. It is saved only in its exported form.
The following JSON content describes a simple control flow with Start, Release, and End Activities. Replace the csrfToken value with the value for your authorization credentials. See "Obtaining a CSRF Token" for more information.
{
"csrfToken": 2c3890b3bb4431a1b47465fbfc58a7d6830c3dbf03b80630767b44225c184ae5,
"name": "example",
"description": null,
"loopsAllowed": false,
"allowedAsLinkedControlFlow": true,
"activities": [
{
"version": 1,
"activityNumber": 1,
"name": "Start",
"activityType": "Start",
"fastKey": "ST",
"location": "420,98,100,60",
"comments": null,
"parameterList": [
{
"key": null,
"attributeList": []
},
{
"key": "Loop Limit",
"attributeList": [
{
"name": "int",
"value": "100"
}
]
},
{
"key": "Loop Limit External",
"attributeList": [
{
"name": "int",
"value": "100"
}
]
},
{
"key": "Loops Allowed",
"attributeList": [
{
"name": "check",
"value": "false"
}
]
}
],
"linkedFlowName": null,
"serviceName": null,
"exit": [
{
"branchNumber": 0,
"branchName": null,
"linkedControlFlowExitActivityNumber": "",
"linkedControlFlowExitActivityName": null,
"connection": [
2
]
}
]
},
{
"version": 1,
"activityNumber": 2,
"name": "Release",
"activityType": "Release",
"fastKey": "REL",
"location": "421,196,100,60",
"comments": null,
"parameterList": [
{
"key": null,
"attributeList": []
},
{
"key": "Session Endpoint",
"attributeList": [
{
"name": "Entries",
"value": "IE:DE"
},
{
"name": "EntriesType",
"value": "EventSource"
},
{
"name": "string",
"value": "IE"
}
]
},
{
"key": "Code",
"attributeList": [
{
"name": "int",
"value": "480"
},
{
"name": "MIN",
"value": "100"
},
{
"name": "MAX",
"value": "699"
},
{
"name": "CORRECTING",
"value": "1"
}
]
}
],
"linkedFlowName": null,
"serviceName": null,
"exit": [
{
"branchNumber": 0,
"branchName": null,
"linkedControlFlowExitActivityNumber": null,
"linkedControlFlowExitActivityName": null,
"connection": [
3
]
},
{
"branchNumber": 0,
"branchName": null,
"linkedControlFlowExitActivityNumber": null,
"linkedControlFlowExitActivityName": null,
"connection": [
3
]
}
]
},
{
"version": 1,
"activityNumber": 3,
"name": "End",
"activityType": "End",
"fastKey": "END",
"location": "426,315,100,60",
"comments": null,
"parameterList": [
{
"key": null,
"attributeList": []
}
],
"linkedFlowName": null,
"serviceName": null,
"exit": []
}
]
}