11 New REST API

API Key

The new API Key is used to authenticate the user when using the new REST API. The API Key is connected to your user account — so when using the REST API with the API Key you have the same access rights as with your user account. Before using the new REST API you first have to enable and generate your personal API Key. The API Key is comprised of the username and a hexcode delimited by a semicolon.

For security reasons the API Key is disabled by default.

To enable your API Key:

1. From the Settings menu, select General Settings, and then select REST API.

2. Select the Enable REST API option, which generates a new API Key.

If the Enable REST API option is deselected, the API Key will automatically be deleted, which disables the REST API. For more information how to use the API Key and the new REST API, see "Getting Started".

Figure 11-1 shows the General Settings REST API page.

Figure 11-1 How to Enable the New REST API

Description of ''Figure 11-1 How to Enable the New REST API''

Getting Started

To get started with using the new REST API please make sure you have your API Key enabled as described in "API Key".

To test if everything is setup correctly please open a terminal window and have your API Key ready. We are going to use the curl command to call the REST API. Please note that this is an example. What we are doing is essentially just placing a HTTPS request with a custom header -X-Api-Key (the custom header contains the API Key). (We use the -k option to make sure that we don't run into any certificate complications when using the API).

Example call:

curl -k -X POST -H "X-API-Key: musterman;samplehexcode" https://mypalladion.com/me/saveApplianceConfiguration
  

Please replace musterman;samplehexcode with your personal API Key. If the API Key is correct and all parameters are provided as per reference, then the HTTP response will be 200 OK with the JSON response containing a success field that will have the value true.

Usecase Backup

With the new REST API it is now possible to create and download savepoints of configurations automatically. To achieve this we are going to use the saveApplianceConfiguration and downloadApplianceConfiguration methods.

First we will call the saveApplianceConfiguration method, which will create a new savepoint on the server and return the name of the savepoint upon success.

In the second step we will then call the downloadApplianceConfiguration method with the filename we just received as a parameter to download the configuration file to our local computer.

The two scripts below automate the task of downloading a configuration savepoint using the two API functions we just discussed. In both scripts it is assumed that the IP address of the instance we want to backup is ME_IP and our API Key is API_KEY.

Python 2.7:

import requests
  
API_KEY = 'username;somehexcode'
URL = 'https://'+ ME_IP  +'/me/'
HEADERS = {'X-Api-Key': API_KEY}
  
resp = requests.get(URL+'saveApplianceConfiguration', headers=HEADERS)
remote_cfg = None
 
if resp.status_code == 200:
   data = resp.json()
   remote_cfg = data['name']
else:
    print('Unexpected status code: ' + str(resp.status_code))
    exit()
  
resp = requests.get(URL+'downloadApplianceConfiguration',
                    headers=HEADERS,
                    params={"name": remote_cfg})
  
if resp.status_code == 200:
    with open(remote_cfg, 'w') as f:
       f.write(resp.text)
else:
    print('Unexpected status code: ' + str(resp.status_code))
  

Even less code is required when Bash scripting is used. The Bash scripting example uses the curl command to call the REST API.

#!/usr/bin/env bash
  
API_KEY="X-Api-Key: username;somehexcode"
URL="https://ME_IP/me/"
SAVE_URL="${URL}saveApplianceConfiguration"
DOWNLOAD_URL="${URL}downloadApplianceConfiguration"
  
remote_cfg=$(curl -k -s -X GET -H"${API_KEY}" $SAVE_URL | grep -Po 'Palladion\-configuration.*\.cfg')
  
curl -k -s -H "${API_KEY}" -d"name=${remote_cfg}" -o ${remote_cfg} $DOWNLOAD_URL

Usecase High Availability

High availability can be achieved by setting up two Mediation Engines — one master and one slave — with a load balancer in front of the two.

In a high-availability setup, it is important to keep the configuration of the master and slave instances synchronized. With the new REST API, you can utilize a simple bash script to download the configuration from the master (as seen in the previous example) and upload and restore it on the slave.

For uploading a configuration file to an instance, use the uploadApplianceConfiguration API call, and for restoring the configuration after it has been uploaded, use the restoreApplianceConfiguration API call.

The following example shows how you can use bash script to automate your setup:

#!/usr/bin/env bash
  
API_KEY="X-Api-Key: my_api_key "
URL="https://my_ip/me/"
UPLOAD_URL="${URL}uploadApplianceConfiguration"
RESTORE_URL="${URL}restoreApplianceConfiguration"
local_cfg="Palladion-configuration-10042014-1.cfg"
  
curl -k -s -X POST -H"${API_KEY}" -F configuration=@"${local_cfg}" ${UPLOAD_URL}
curl -k -s -X POST -H"${API_KEY}" -d"configuration=${local_cfg}" ${RESTORE_URL}

Examples

List the last 20 calls:

curl -k -X POST -H "X-API-Key: API_Key" -d "limit=20" "https://IP:Port/me/getPagedCalls"
  

where,

• API_Key, is your personal key code. For more information on how to generate this key, see "API Key".

• IP, is the IP address of Oracle Communications Session Monitor Mediation Engine.

• Port, is the port number of the SSL web interface of Mediation Engine. The :Port section can be omitted if the default HTTPS port (443) is used.

Get the next 20 calls (after executing the previous example):

curl -k -X POST -H "X-API-Key: API_Key" -d "limit=20&older_than=next_value"
"https://IP:Port/me/getPagedCalls"
  

Where next_value is the returned content of the next_value field from the previous example.

List all failed calls starting from last week, from a specific caller:

curl -k -X POST
-H "X-API-Key:API_Key"
-d 'filters=[{"field":"src_user","data":{"type":"string","value":"src_user"}},
{"field":"setup_start_ts","data":{"type":"datetime","comparison":"gt",
"value":"start_date"}},
{"field":"state_msg","data":{"type":"list","value":["Failed"]}}]'
"https://IP:Port/me/getPagedCalls"
  

Where,

• src_user, is the ID of the user whose failed calls your retrieving.

• start_date, specifies the starting date to retrieve failed calls. The format is YYYY-MM-DD hh:mm:ss, for example 2015-04-13 00:00:00.

Reference

This section lists the most common API calls. However if you want to access a feature of Operations Monitor through the new REST API that is not listed here, see "Reverse Engineering of API Calls".

{"field":"<field>","data":{"type":"<type>","comparison":"<comparison>",
"value":"<value>"}}
  

”<Media type>#<src_ip>:<src_port>#<dst_ip>:<dst_port>#<media_content_type>”
  

”MEDIA#62.220.31.225:19848#62.220.31.239:27998#rtp_full”
  

Reverse Engineering of API Calls

As stated earlier, the above documentation only covers the most important features of the new REST API. With the new API Key however you have the same access to the features of Operations Monitor as with the regular web interface. So in the following section we will be using the Google Chrome browser's development tools to reverse engineer how to use API calls that are not documented here. You can also follow this guide using the Mozilla Firefox browser in conjunction with the Firebug extension. It is a fairly straightforward process though - so if you're impatient go ahead and use the web interface of Operations Monitor and watch the network activity while you're at it to figure out how to use parts of the API not covered here. For an in-depth guide how to achieve this goal please continue reading.

getSystemSettings/?_dc=1398269727192
  

As you might recall Operations Monitor has a feature for saving calls (you might have noticed that in many Calls related API calls you can pass a saved_id for identifying a call instead of the id and the pid). If we were to use that functionality through a script an interesting use case might be to save certain calls in the course of an operation, in order to have a human user review these later.

So let's find out, how to save calls using the new REST API. In order to walk you through the process you need to have a good understanding of how the new REST API works. If you think you might need a refresher on that please head over to the API Key and the Getting Started sections and have a quick look at our use cases Usecase Backup and Usecase High Availability.

To get started, please retrieve your API Key, and have your tools ready for action.

Next go to the Calls section in the web interface of Operations Monitor, which is shown in Figure 11-2:

Figure 11-2 The Calls Section in the Main Menu

Description of ''Figure 11-2 The Calls Section in the Main Menu''

Go ahead and open the developer tools so that we know what's going on in the background. Click the Customize and control Google Chrome icon to access Developer Tools as shown in Figure 11-3:

Figure 11-3 Accessing the Google Chrome Developer Tools

Description of ''Figure 11-3 Accessing the Google Chrome Developer Tools''

Please make sure that you have the Network tab open and that recording is enabled, as shown in Figure 11-4 , so that we can observe the network activities that are happening in the background while using the web interface of Operations Monitor.

Figure 11-4 Enable Recording

Description of ''Figure 11-4 Enable Recording''

In the Recent calls section of the web interface of Operations Monitor, double click on any call to open up the call details dialog, as shown in Figure 11-5.

Figure 11-5 Double Click on a Call to See Details

Description of ''Figure 11-5 Double Click on a Call to See Details''

On the bottom of the now open dialog you will find a set of buttons, including a Save button as shown in Figure 11-6. Please place your mouse cursor above that button and use it by firmly pressing your left mouse button.

Figure 11-6 Save Button

Description of ''Figure 11-6 Save Button''

Now it's time to name the to be saved call. Please use the name TestSavedCall123456789 or a name that will be easily recognizable as your custom name as shown in Figure 11-7.

Figure 11-7 Adding a Custom Name

Description of ''Figure 11-7 Adding a Custom Name''

Next, if you click Save, you should see a saveCall https call popup in the network monitoring section of the developer tools as shown in Figure 11-8. You may go ahead and stop the recording of network activity at this point as we have all the info we need to find out how to use this call in the future.

Figure 11-8 saveCall https Call Popup

Description of ''Figure 11-8 saveCall https Call Popup''

Scroll down to the section Form Data as shown in Figure 11-9.

Figure 11-9 The Form Data Section of the saveCall Request

Description of ''Figure 11-9 The Form Data Section of the saveCall Request''

Here we can easily read out the parameters for the saveCall request:

• pid

  The Process ID of the call we opened and saved.

• id

  The ID of the call we saved.

• name

  The name for the saved call as previously entered.

If you now switch to Preview tab of the request we can discover the returns of this call as shown in Figure 11-10:

Figure 11-10 Preview Tab

Description of ''Figure 11-10 Preview Tab''

• saved_id

  The saved_id of the call we just saved. In the future we may use this to identify this call instead of using the id and pid parameter.

• success

  This field is always part of the return if no error occurred.

And with that you now know how to save calls using the new REST API. You can use the same approach for any other functionality in the web interface of Operations Monitor that you would like to automate.

All you have to do is to play around with the web interface a bit and see how requests behave differently based on changes you perform.