1. Operations Monitor User Guide
  2. New REST API
  3. Reference

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".

Note:

All parameter names and options (given in round brackets, separated by vertical lines) are case sensitive.

Note:

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.

Fundamental Concepts

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.

Configuration Savepoints

Note:

For security reasons, REST APIs are not stored in configuration savepoint.

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).

Calls

Table 11-7 describes the /me/getPagedCalls call object.

Table 11-7 /me/getPagedCalls

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.

Filter Design Template

{"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.

Creating a Filter for a Specific Column

To create a filter for a specific column:

  1. Locate the <field> value for the desired column (see the Field (<field>) column in Table 11-8).

  2. Locate the type of the column (see the Type column in Table 11-8).

  3. Refer to Table 11-10 to see which filters are available and how to use them.

  4. 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:

  • To filter to True, set type to string and comparison to notnull.

  • To filter to False, set type to string and comparison to null.

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:

  • To filter for Successfull Session Request Delay include 1 (as a String) in the list you pass for <value>.

  • To filter for Failed Session Request Delay include the String 2 in the list you pass for <value>.

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:

  • To filter to True, set type to string and comparison to notnull.

  • To filter to False, set type to string and comparison to null.

state_details

String

State details

state_msg

List

State

Options are as follows:

  • Blocked

  • Busy

  • Canceled

  • Error

  • Established

  • Failed

  • Finished

  • Not Found

  • Off-line

  • On hold

  • Proceeding

  • Redirected

  • Reset

  • Ringing

  • Setup

  • Terminate

  • Timed out

  • Unauthorized

  • Unequipped

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.
  • Green - Calls in Established State
  • Black - Calls in Finished State
  • Red - Timed-Out or Failed
  • Orange - Cancelled/Offline Calls

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:

  • legs - Array with the legs of the call.

  • megaco_id - Megaco ID.

  • merged_into_call_id

  • total_legs - Total amount of legs.

Internal only fields:

  • mgcp_id

  • mgcp_mgc_ip

  • mgcp_txids

  • mgcp_verbs

  • traversing_devs

Table 11-12 describes the /me/getCallMsgs call object.

Table 11-12 /me/getCallMsgs

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.

Table 11-13 /me/getCallsTime

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.

Table 11-15 /me/callPcap

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.

Registrations

Table 11-16 describes the /me/getRegsPaged registrations object.

Table 11-16 /me/getRegsPaged

Description Method Parameters Returns

Retrieves a list of registrations around a point in time or around another registration.

POST

filters

See the Filter Design Template section to design your own filters.

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:

  • dev_id – Registrar.

  • code – Code.

  • contacts – Contacts.

  • ip – Source IP address.

  • ts – Timestamp.

  • type_msg – Event.

  • user – User.

  • dest_ip – Destination IP address.

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.

Table 11-17 /me/getRegsTime

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.

Table 11-18 /me/getRegEvent

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.

Table 11-19 /me/getRegEvMsgs

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.

Fields and Types for getRegsPaged

Table 11-20 /me/getRegsPaged

Field (<field>) Type Column in the Calls Table
user strings User
contacts strings Contacts
ip strings Source IP address
dest_ip strings Destination IP addresss
ts datetime Timestamp
dev_id list Registrars
type_msg list Event
  • New
  • Failed
  • Unauthorized
  • Expired
  • Gone
code numeric Code

KPI

Table 11-21 describes the /me/getCounterValues KPI object.

Table 11-21 /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-22 describes the /me/addOrModifyCounter KPI object.

Table 11-22 /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:

  • weekdays

    (Optional) Set weekdays to 1 if you want the average to be taken only over weekdays otherwise set it to 0.

  • days

    (Optional) The average will be taken over the amount of days specified here.

  • name

    (Optiona) The name for the average counter.

id

ID of the added or changed counter.

Table 11-23 describes the /me/deleteCounter KPI object.

Table 11-23 /me/deleteCounter

Description Method Parameters Returns

Removes a counter.

POST

id

ID of the counter to be removed.

None.

Table 11-24 describes the /me/toggleSNMPExport KPI object.

Table 11-24 /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-25 describes the /me/getCounterRealm KPI object.

Table 11-25 /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-26 describes the /me/getCounterConfig KPI object.

Table 11-26 /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:

  • id – ID of the counter (numeric).

  • name – Name of the counter.

  • service_id – Internal only.

  • maintype – Numeric main type of the counter.

  • subtype – Numeric sub type of the counter.

  • snmp_export – Boolean if snmp export is enabled.

  • src_cnt – For average counters, the source counter for the average.

  • weekdays – For average counters, whether the average is calculated for each weekday separately.

  • days – For average counters, whether the average is calculated for each weekday separately.

  • param1 – First counter parameter.

  • param2 – Second counter parameter.

  • param3 – Third counter parameter.

Table 11-27 describes the /me/getSimpleCounters KPI object.

Table 11-27 /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:

  • id – ID of the counter (numeric).

  • name – Name of the counter.

  • subtype – Numeric sub type of the counter.

  • owner – Owner of the counter.

  • params – List with the first, second and third parameter of the filter

Table 11-28 describes the /me/getCounters KPI object.

Table 11-28 /me/getCounters

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:

  • id – ID of the counter (numeric).

  • maintype – Main type of counter.

  • name – Name of the counter.

  • subtype – Numeric sub type of the counter.

  • owner – Owner of the counter.

  • params – List with the first, second and third parameter of the filter.

Table 11-29 describes the /me/counters KPI object.

Table 11-29 /me/counters

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-30 describes the /me/getCounterTotal KPI object.

Table 11-30 /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-31 describes the /me/getCounterTypes KPI object.

Table 11-31 /me/getCounterTypes

Description Method Parameters Returns

Gets the counter types with names and parameters.

POST

All parameters are optional:

  • device_id

    Device ID of counter.

  • device_list

    List of devices.

  • iptag_list

    List of IP tags.

  • iptag_id

    IP tag ID.

  • tag_id

    Tag ID.

  • only_active

    (true | false) Whether to return only active counters.

  • remove_create_new

    Description.

List with counters, fitting the given parameters.

Table 11-32 describes the /me/MonitorGraph KPI object.

Table 11-32 /me/MonitorGraph

Description Method Parameters Returns

Draws and returns a counter graph.

POST

All parameters are optional:

  • period

    int - period in seconds.

  • utcdate

    date in format ‘2012-10-31T20:16:52Z'.

  • format

    Call returns a SVG image, if parameter is “svg"- else returns a PNG image (or JSON- see raw_data).

  • raw_data

    (true | false) If True, return json, no image.

  • selected

    A list of IDs to determine which metrics to render.

  • tzoffset

    Offset for the time zone.

data

JSON object with the raw data in case raw_data was set to true.

Else the requested image file.