With the new REST API almost all Oracle Communications Operations Monitor features are now easily accessible through HTTPS REST calls. Nearly every feature you already use through the web interface of Operations Monitor can now be automated and used with your HTTPS capable toolchain of choice.
Plus with the new API Key, authentication is now more simple and secure than before. Authentication is now as simple as passing your personal API Key along with your request.
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:
From the Settings menu, select General Settings, and then select REST API.
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".
Important:
It is strongly recommended that you store your API Key in a safe and secret place. For example, your script's configuration files.Important:
After closing the Settings dialog box the API Key will no longer be displayed. The API Key is displayed only once when it is first created.Figure 11-1 shows the General Settings REST API page.
Figure 11-1 How to Enable the New REST API
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.
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
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}
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.
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".
Note:
All parameter names and options (given in round brackets, separated by vertical lines) are case sensitive.Important:
All parameters are mandatory with all REST API calls unless marked as optional. This is not enforced by the server. For many parameters fall back values are defined. You are strongly advised not to rely on these fall back values as any software updates could break your code in the case that fall back values have been changed.Please note that there are some basic principles to the new REST API that you should know in order to have a better understanding of the API:
All REST API calls are made using HTTPS. Any requests using plain HTTP will result in a HTTP/1.1 301 Moved Permanently.
All parameters of calls are transmitted as HTTP header fields.
Responses are JSON Objects.
If the API call succeeded the response will be a 200 Ok HTTP message and the success field of the response will have the value true.
If a call doesn't succeed, the response will be a 200 Ok HTTP message too. The success field of the response however will be false and there will be a field errorMsg containing a brief description of what went wrong.
Note:
In some cases instead of a 200 Ok HTTP message, a 404 type message will be returned. In this rare event instead of a JSON object a HTML string, containing an error page, will be returned. So please be sure to also check for 404, and 301 HTTP responses (see above) when checking for errors!Often calls have a method for limiting the result set. This is done just as in the database world where you can specify from which element you want to start and how many elements you want to have returned at most.
The filtering concept that is used in getPagedCalls is also available for any other data that is being presented as a sortable grid with optional filters in Operations Monitor. For more information on how to design filters and reverse engineer the API for any other data accessible through Operations Monitor, see "Examples" and "Reverse Engineering of API Calls".
In order to get a better understanding of all these concepts please feel free to play around with the little snippets presented in the "Examples" section.
Table 11-1 describes the /me/saveApplianceConfiguration savepoint object.
Table 11-1 /me/saveApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Creates a savepoint on the server and returns the name of the savepoint. |
POST |
None. |
name Name of the save point. |
Table 11-2 describes the /me/uploadApplianceConfiguration savepoint configuration.
Table 11-2 /me/uploadApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Uploads a savepoint to the Server and returns the name of the savepoint. |
POST |
configuration Local file name. name ”configuration”. |
name Name of the save point on the server. |
Table 11-3 describes the /me/downloadApplianceConfiguration savepoint object.
Table 11-3 /me/downloadApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Downloads a previously saved or uploaded configuration savepoint. |
POST |
name Name of the savepoint to be downloaded. |
The requested file. File name is included in the content-disposition Response Header field. |
Table 11-4 describes the /me/restoreApplianceConfiguration savepoint object.
Table 11-4 /me/restoreApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Restores a previously saved to uploaded savepoint. |
POST |
configuration Name of the savepoint to be restored. |
warnings Warnings that occurred during the restore process, separated by newline characters. |
Table 11-5 describes the /me/deleteApplianceConfiguration savepoint object.
Table 11-5 /me/deleteApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Deletes a savepoint. |
POST |
name Name of the savepoint to be deleted. |
None. |
Table 11-6 describes the /me/listApplianceConfigurations savepoint object.
Table 11-6 /me/listApplianceConfigurations
Description | Method | Parameters | Returns |
---|---|---|---|
Gets list of save points. |
POST |
start Starting offset for the results to be returned. limit Limits the number of results to be returned. sort Column by which to sort the results (”date” | ”name”). dir Whether to sort results ascending or descending (”ASC” | ”DESC”). |
configurations Array with informations about the individual savepoints. totalCount Number of savepoints in total (not the number of returned savepoints). |
Table 11-7 describes the /me/getPagedCalls call object.
Description | Method | Parameters | Returns |
---|---|---|---|
Gets a list of calls around a given point in time or around a given call. |
POST |
filters See the filter design template and the tables below to design your own filters for the result set. If you do not want to filter the result set, please pass an empty list instead ([]). older_than Pass an ID of an element of the result set here to retrieve elements older than the given element. older_than_ts Same as the above, only here you pass the timestamp of an object, not its ID. newer_than, newer_than_ts Same as the above, just into the opposite direction. limit Limits the amount of results to be returned. |
calls Array with calls objects. See the below table for details. first_page Whether or not the returned result set is the first page of results available (true | false). last_page Whether or not the returned result set is the last page of results available (true | false). next_value When you want to retrieve the next page of results using the same parameters, use next_value for the older_than field in the request header. |
{"field":"<field>","data":{"type":"<type>","comparison":"<comparison>", "value":"<value>"}}
Where:
<field> is the name of the field that the filter applies to.
<type> is the type of the filter. Depending on the type of the field there are different filters available. See Table 11-10 for details.
<comparison> is the comparator to be used for filtering. See Table 11-10 for details.
<value> is the value to compare against in the filter. See Table 11-10 for details.
To create a filter for a specific column:
Locate the <field> value for the desired column (see the Field (<field>) column in Table 11-8).
Locate the type of the column (see the Type column in Table 11-8).
Refer to Table 11-10 to see which filters are available and how to use them.
Refer to "Examples" and "Reverse Engineering of API Calls" for in depth examples on how to use getPagedCalls and how to watch network traffic to get a better understanding of the API.
Table 11-8 lists the columns and fields in the calls objects that can be filtered.
Note:
Table 11-9 lists fields, which are also part of the calls objects that cannot be filtered.Table 11-8 Fields and Types (in alphabetical order)
Field (<field>) | Type | Column in the Calls Table |
---|---|---|
call_time |
Numeric |
Call time |
code |
Numeric |
Code |
dpc |
String |
DPC |
dst_codecs |
String |
Callee Codecs |
dst_initial_codecs |
String |
Callee Initial Codecs |
dst_ip |
IP address |
Callee IP address. For the data field of the filter, set type to ipaddr and value to the IP address string (e.g. 192.168.1.123 or 10.0.0.0/8). |
dst_ua |
String |
Callee User Agent |
dst_user |
String |
Callee |
dst_user_pref_tag |
Boolean |
Preferred Callee Number? For the data field of the filter:
|
dtmf |
Boolean |
DTMF |
egress_devs |
List |
Egress device(s) |
end_ts |
Datetime |
End timestamp |
gateway_devs |
List |
Gateway Devices |
in_devs |
List |
In devices |
ingress_devs |
List |
Ingress device(s) |
init_devs |
List |
Initiator device |
megaco_cmds |
String |
MEGACO Commands |
megaco_context_id |
String |
MEGACO Context ID |
megaco_mg_ip |
String |
MEGACO Gateway |
megaco_mgc_ip |
String |
MEGACO Gateway Controller |
megaco_termination_id |
String |
MEGACO Termination ID |
megaco_txids |
String |
MEGACO Transaction IDs |
mgcp_call_ids |
String |
MGCP Call IDs |
mgcp_capabilities |
String |
MGCP Capabilities |
mgcp_connection_ids |
String |
MGCP Connection IDs |
mgcp_mg_ip |
String |
MGCP Gateway IP |
MOSlqe_avg |
Numeric |
Avg. MOS |
MOSlqe_min |
Numeric |
Min. MOS |
nlegs |
Numeric |
Segments |
opc |
String |
OPC |
out_devs |
List |
Out devices |
pai |
String |
P-Asserted-ID |
prefix_group |
List |
Prefix Group |
q850_code |
Numeric |
Q.850 Code |
q850_state_details |
String |
Q.850 Details |
q850_state_msg |
String |
Q.850 State |
realms_recordings |
Boolean |
Media For the data field of the filter, set type to custom:streams_availability and value to false, or true depending on which you want to filter for. |
reason_hdr |
|
Reason |
rpid |
String |
Remote-Party-ID |
rtcp_delay_avg |
Numeric |
Avg RTCP delay |
rtcp_delay_max |
Numeric |
Max RTCP delay |
rtcp_streams |
Numeric |
RTCP streams |
setup_delay |
Numeric |
Setup Delay |
setup_delay_type |
List |
Setup Delay Type With this column you have two options which you can filter for. You may filter for either one, or both options:
|
setup_start_ts |
Datetime |
Start timestamp |
setup_time |
Numeric |
Setup time |
src_codecs |
String |
Caller Codecs |
src_initial_codecs |
String |
Caller Initial Codecs |
src_ip |
IP address |
Caller IP address. For the data field of the filter, set type to ipaddr and value to the IP address string (e.g. 192.168.1.123 or 10.0.0.0/8). |
src_ua |
String |
Caller User Agent |
src_user |
String |
Caller |
src_user_pref_tag |
Boolean |
Preferred Caller Number? For the data field of the filter:
|
state_details |
String |
State details |
state_msg |
List |
State Options are as follows:
You may filter for one or more of the above options. Just include the desired value(s) from the above list as Strings in the array you pass for <value>. |
term_devs |
List |
Terminator device |
Table 11-9 lists fields that are not in the above table (cannot be filtered) but are part of the calls objects:
Table 11-9 Call Object Fields that Cannot be Filtered
Field | Description |
---|---|
pid |
Process ID. |
id |
ID of the call. A call is uniquely identified through its pid and id. |
id32 |
Internal only. |
strictly_increasing |
ID which can be used for sorting call events chronologically. |
state |
Numeric representation of state. |
state_cls |
Color of state. |
end_ts |
Timestamp of when the call was finished. |
mos_cls |
Color of the mos column. |
overload |
Whether during the processing of the call a system overload occurred. |
number_prefix |
Contains a comma separated list for all the number prefixes, that the respective call is matching. |
Table 11-10 lists all available filter types. Please note that the table has been grouped by column data type (see above table) to show which filter options are available for the corresponding field type.
Table 11-10 Filter Types (grouped by column data types)
Type (<type>) | Comparators (<comparison>) | Description |
---|---|---|
String exactstring string |
None. None. |
Matches exact string. Match string. |
DateTime date
datetime datetime_utc |
lt gt eq neq leq geq (lt | gt | eq | neq | leq | geq) (lt | gt | eq | neq | leq | geq) |
less than (before given date) (<). greater than (after given date) (>). equal (on the given date) (=). not equal (not on the given date) (!=). less or equal (on or before the given date (<=). greater or equal (on or after the given date) (>=). Equals only compares dates. Equals only compares dates. Use this version if <value> is a UTC timestamp. |
Numeric numeric |
(lt | gt | eq | neq | leq | geq) |
Does the job of any first grader only slightly faster. |
List in_list list not_in_list |
None. None. None. |
Matches one value of the array given in <value>. Matches at least one element of the array given in <value>. Does not match a value of the array given in <value>. |
Table 11-11 describes the /me/getCallDetails call object.
Table 11-11 /me/getCallDetails
Description | Method | Parameters | Returns |
---|---|---|---|
After you called getPagedCalls to retrieve a list of calls you can use getCallDetails to obtain further information about a specific call. |
POST |
id ID of call as returned in the id field of a call. pid As returned in the pid field of a call. saved_id (Optional) Instead of passing the previous two IDs you can just pass this ID in case you saved this call. no_legs (true | false). |
An array with essentially the same fields as getPagedCalls but also a few additional fields:
Internal only fields:
|
Table 11-12 describes the /me/getCallMsgs call object.
Description | Method | Parameters | Returns |
---|---|---|---|
Returns the SIP messages associated with a given call. |
POST |
id ID of call as returned in the id field of a call. pid As returned in the pid field of a call. saved_id (Optional) Instead of passing the previous two IDs you can just pass this ID in case you saved this call. |
proto Protocol. src_ip Source IP. src_mac Source Mac. opc Source PC. dst_ip Destination IP. dst_mac Destination MAC. dpc Destination PC. ts Date and Time. method Message. ruri Details |
Table 11-13 describes the /me/getCallsTime call object.
Description | Method | Parameters | Returns |
---|---|---|---|
Returns the current time stamp (for use in for example getPagedCalls as value for the older_than_ts parameter) and the time stamp of the latest call. |
POST |
None. |
ts_first Timestamp of the first call in the database. ts_now Current timestamp - can be used as a value for older_than_ts. For example in getPagedCalls. |
Table 11-14 describes the /me/getAvailablePcaps call object.
Table 11-14 /me/getAvailablePcaps
Description | Method | Parameters | Returns |
---|---|---|---|
Get the available pcaps and the streams available in the respective pcap. |
POST |
id ID of call as returned in the id field of a call. pid As returned in the pid field of a call. saved_id (Optional) Instead of passing the previous two IDs you can just pass this ID in case you saved this call |
available An object which contains all available recorded streams for the specified user grouped by stream type. |
Table 11-15 describes the /me/callPcap call object.
Description | Method | Parameters | Returns |
---|---|---|---|
Download a pcap file for a specific call. |
POST |
id ID of call as returned in the id field of a call. pid As returned in the pid field of a call. saved_id (Optional) Instead of passing the previous two IDs you can just pass this ID in case you saved this call. filename If this is not empty it is going to be the filename of the pcap file that is retrieved from the server. streams Array which includes which stream types you would like to retrieve. Include the string "EN10MB" in the array to include signaling messages, and for every stream for which you want to retrieve the RTP payload include a string of the format: ”<Media type>#<src_ip>:<src_port>#<dst_ip>:<dst_port>#<media_content_type>” Example: ”MEDIA#62.220.31.225:19848#62.220.31.239:27998#rtp_full” If the above fields are not familiar please make sure to experiment with getAvailablePcaps and play around with the RTP recording feature and the save PCAP feature in the regular Operations Monitor web interface. |
The requested pcap file. |
Table 11-16 describes the /me/getRegsPaged registrations object.
Description | Method | Parameters | Returns |
---|---|---|---|
Retrieves a list of registrations around a point in time or around another registration. |
POST |
None older_than Pass an ID of an element of the result set here to retrieve elements older than the given element. older_than_ts Same as the above, only here you pass the timestamp of an object- not its ID. newer_than, newer_than_ts Same as the above, just into the opposite direction. |
data Array containing all registrations of the current result set. Fields contained in data:
first_page Whether or not the returned result set is the first page of results available (true | false). last_page Whether or not the returned result set is the last page of results available (true | false). next_value When you want to retrieve the next page of results using the same parameters, use next_value for the older_than field in the request header. |
Table 11-17 describes the /me/getRegsTime registrations object.
Description | Method | Parameters | Returns |
---|---|---|---|
Returns the current time stamp (for use in for example getPagedRegs as value for the older_than_ts parameter) and the timestamp of the latest registration. |
POST |
None. |
ts_first Timestamp of the first registration result set using the passed filters. ts_now Current timestamp- can be used as a value for older_than_ts for example in getPagedCalls. |
Table 11-18 describes the /me/getRegEvent registrations object.
Description | Method | Parameters | Returns |
---|---|---|---|
Gets details about a registration event. |
POST |
id ID of the event for which you want to retrieve the SIP messages. |
reg Array containing the SIP messages for the specified event. |
Table 11-19 describes the /me/getRegEvMsgs registrations object.
Description | Method | Parameters | Returns |
---|---|---|---|
Gets the SIP messages for a specified event. |
POST |
id ID of the event for which you want to retrieve the SIP messages. start Starting offset for the results to be returned. limit Limits the amount of results to be returned. |
totalCount Total count of the result set - not the amount of elements returned. data Array with the requested SIP messages. |
Table 11-20 describes the /me/getCounterValues KPI object.
Table 11-20 /me/getCounterValues
Description | Method | Parameters | Returns |
---|---|---|---|
Returns counters marked as favorites and their recent values. |
POST |
None. |
counters An array containing the requested counters. |
Table 11-21 describes the /me/addOrModifyCounter KPI object.
Table 11-21 /me/addOrModifyCounter
Description | Method | Parameters | Returns |
---|---|---|---|
Add or modify a counter. |
POST |
action Whether to edit or add a counter (”add” | ”edit”). snmp_export (Optional) Set this to ”on” to enable snmp export, or do not use this parameter to disable snmp export. maintype Numeric representation of the counter. Use getCounterTypes to find out the main types of counters. subtype Numeric representation of the counter. Use getCounterTypes to find out the subtypes of counters. If you want to create an average counter include the three properties below:
|
id ID of the added or changed counter. |
Table 11-22 describes the /me/deleteCounter KPI object.
Description | Method | Parameters | Returns |
---|---|---|---|
Removes a counter. |
POST |
id ID of the counter to be removed. |
None. |
Table 11-23 describes the /me/toggleSNMPExport KPI object.
Table 11-23 /me/toggleSNMPExport
Description | Method | Parameters | Returns |
---|---|---|---|
Enables or disables the SNMP export of a counter. |
POST |
ids List of counter IDs. action (’enable' | ’disable'). |
None. |
Table 11-24 describes the /me/getCounterRealm KPI object.
Table 11-24 /me/getCounterRealm
Description | Method | Parameters | Returns |
---|---|---|---|
Get a counter's realm. |
POST |
id ID of the counter. |
realm Realm of the given counter. |
Table 11-25 describes the /me/getCounterConfig KPI object.
Table 11-25 /me/getCounterConfig
Description | Method | Parameters | Returns |
---|---|---|---|
Retrieves the configuration of a user counter. You can modify the returned configuration and pass it to addOrModifyCounter to update/create a counter with the modified configuration. |
POST |
id ID of the user counter to be retrieved. |
data An object with the configuration fields of the desired counter:
|
Table 11-26 describes the /me/getSimpleCounters KPI object.
Table 11-26 /me/getSimpleCounters
Description | Method | Parameters | Returns |
---|---|---|---|
Gets counters which are no average counters. |
POST |
device_id Device ID of the counter. tag_id Tag ID of the counter. |
counters Object containing the following fields:
|
Table 11-27 describes the /me/getCounters KPI object.
Description | Method | Parameters | Returns |
---|---|---|---|
Gets all types of counters- even if they are average counters. |
POST |
device_id Device ID of the counter. tag_id Tag ID of the counter. |
counters Object containing the following fields:
|
Table 11-28 describes the /me/counters KPI object.
Description | Method | Parameters | Returns |
---|---|---|---|
Get all visible counter IDs. |
POST |
alias (true | false) Whether or not to include the user's aliases in the search for counters. |
counters List with IDs of visible counters. |
Table 11-29 describes the /me/getCounterTotal KPI object.
Table 11-29 /me/getCounterTotal
Description | Method | Parameters | Returns |
---|---|---|---|
Gets the current and maximum allowed amount of counters. |
POST |
None. |
total Total count of current counters. max_counters Maximum possible amount of counters. counters_lock Whether there is currently an operation on the counters active. |
Table 11-30 describes the /me/getCounterTypes KPI object.
Table 11-30 /me/getCounterTypes
Description | Method | Parameters | Returns |
---|---|---|---|
Gets the counter types with names and parameters. |
POST |
All parameters are optional:
|
List with counters, fitting the given parameters. |
Table 11-31 describes the /me/MonitorGraph KPI object.
Description | Method | Parameters | Returns |
---|---|---|---|
Draws and returns a counter graph. |
POST |
All parameters are optional:
|
data JSON object with the raw data in case raw_data was set to true. Else the requested image file. |
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.
Note:
When watching the network activity of Operations Monitor you will often see URLs that have a weird suffix.For example:
getSystemSettings/?_dc=1398269727192
The suffix is pretty much a timestamp appended by our frontend framework. This is done to avoid any possible caching of HTTP requests by altering the URL with the timestamp. This is done to ensure that any results are always directly from the server and not any outdated, cached results.
This scenario is very unlikely however and is merely a workaround to bad network configuration. You can go ahead and ignore this parameter when analyzing backend calls and leave the parameter out when using backend calls from a custom script.
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
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
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.
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
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.
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.
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.
Scroll down to the section Form Data as shown in Figure 11-9.
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:
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.