Interface Description
The resources accessible via the REST interface are encoded in JSON. You can access the following resources on each Operations Monitor system (with variables denoted in angle brackets):
/r/calls
A structure containing information about the available calls. It contains the fields listed in Table 10-1:
Table 10-1 /r/calls Fields
| Field | Description |
|---|---|
|
end_call_id |
The call ID of the last call. |
|
end_ts |
A timestamp giving the second in which the last call was started. |
|
name |
Is always calls. |
|
start_call_id |
The call ID of the first call (not the same ID used in conjunction with a partition ID). |
|
start_ts |
A timestamp giving the second in which the first call was started. |
|
total |
The number of calls in the partition. |
Note:
In the Operations Monitor version before 3.1 this method returned a list of structures with partitioning information. Starting with version 3.1, partitions are no longer used.
/r/calls/recent
The list of recent calls similar to the one that is displayed in the recent calls table in the web interface. This resource is a list resource and has the common format of list resources and allows filtering and paging. For more information, see "The Format of List Resources".
The list items are structures consisting of the fields listed in Table 10-2:
Table 10-2 /r/calls/recent Fields
| Field | Description |
|---|---|
|
call_time |
The time the call was in state ESTABLISHED. |
|
code |
The code of the last response for the first INVITE message. |
|
dst_codecs |
The codecs proposed by the callee. |
|
dst_initial_codecs |
The codecs initially proposed by the callee. |
|
dst_ip |
The IP address of the called user that connected first. This may be an empty string. |
|
dst_ua |
The user agent of the callee. |
|
dst_user |
The identifier of the callee. |
|
egress_devs |
The egress device(s). |
|
id |
Together with pid makes up the unique identifier of a call. |
|
in_devs |
The in device(s). |
|
ingress_devs |
The ingress device(s). |
|
init_devs |
The initiator device. |
|
MOSlqe_avg |
The average MOS estimation for this call. |
|
MOSlqe_min |
The minimum MOS estimation for this call. |
|
nlegs |
The number of legs in the call. |
|
out_devs |
The out device(s). |
|
pid |
Together with id makes up the unique identifier of a call. |
|
realms |
A bitmask of the realms this call belongs to. |
|
setup_start_ts |
The time the first INVITE message was issued. |
|
setup_time |
The time before the call reached the state ESTABLISHED. |
|
src_codecs |
The audio codecs proposed by the caller. |
|
src_initial_codecs |
The audio codecs initially proposed by the caller. |
|
src_ip |
The IP address of the device initiating the call. This includes the IP address string. |
|
src_ua |
The user agent of the caller. |
|
src_user |
The caller identifier. |
|
state_details |
Details about the current state of the call. |
|
state_msg |
The current state of the call. |
|
term_devs |
The terminator device. |
|
url |
The url of the full call rest resource. |
/r/calls/<start_ts>/<end_ts>
A list of calls started between <start_ts> and <end_ts>. This list is structured exactly like the list of recent calls, but the calls are from a definable timespan. The timestamps have to be written in ISO 8601 format and then be url encoded.
The following query gets the calls started between, 22 Mar 2010 16:30 and 22 Mar 2010 17:00:
$ curl -L -user admin:<passwd> https://10.1.0.81/r/calls/2010-03- 22+16:30:00/2010-03-22+17:00:00
A list of calls might be filtered by following parameters:
-
MOSlqe_avg
-
MOSlqe_min
-
init_devs
-
term_devs
-
traversing_devs
-
ingress_devs
-
egress_devs
-
gateway_devs
For Example:
$ curl -L -user admin:<passwd> https://10.1.0.89/r/calls/2014-01- 01+00:00:00/2014-02-01+00:00:00?term_devs__eq=52
/r/calls/<start_ts>/<end_ts>/<pid>:<id>
The call with the given <pid> and <id>. The returned resource is a structure with the fields listed in Table 10-3:
Table 10-3 /r/calls/<start_ts>/<end_ts>/<pid>:<id> Fields
| Field | Description |
|---|---|
|
call_id |
An identifier that makes up a unique identifier of a call. Can be used instead of <pid> and <id>. |
|
call_time |
The time the call was in state ESTABLISHED. |
|
code |
The code of the last response for the first INVITE message. |
|
dst_user |
The identifier of the callee. |
|
id |
Together with pid makes up the unique identifier of a call. |
|
legs |
A list of legs belonging to this call. |
|
messages_url |
The url of the messages resource for this call. |
|
nlegs |
The number of legs in the call. |
|
pid |
Together with id makes up the unique identifier of a call. |
|
realms |
A bitmask of the realms this call belongs to. |
|
setup_start_ts |
The time the first INVITE message was issued. |
|
setup_time |
The time before the call reached state ESTABLISHED. |
|
src_user |
The caller identifier. |
|
state_details |
Details about the current state of the call. |
|
state_msg |
The current state of the call. |
|
vq_url |
The url of the voice quality resource for this call. |
Note:
<call_id> can be used to identify a call instead of the <pid>:<id> combination.
/r/calls/<start_ts>/<end_ts>/<pid>:<id>/messages
A representation of the SIP messages of a given call. This resource is a list resource and has the common format of list resources and allows paging but not filtering. For more information, see "The Format of List Resources".
The list items are structures with the fields listed in Table 10-4:
Table 10-4 /r/calls/<start_ts>/<end_ts>/<pid>:<id>/messages Fields
| Field | Description |
|---|---|
|
code |
If the message is a response message - the response code. |
|
data |
The whole message as a string. |
|
dst_ip |
The destination IP address. |
|
dst_mac |
The destination hardware address. |
|
dst_port |
The destination port. |
|
method |
If the message is a request message - the request method. For example, INVITE or ACK. |
|
msgid |
The unique ID of this message. |
|
proto |
UDP or TCP. |
|
reason |
If the message is a response message - the response reason. |
|
ruri |
If the message is a request message - the request uri of this message. |
|
src_ip |
The source IP address. |
|
src_mac |
The source hardware address. |
|
src_port |
The source port. |
|
ts |
The time this message was received by Operations Monitor. |
/r/calls/<start_ts>/<end_ts>/<pid>:<id>/vq
Voice quality information for each RTP stream that belongs to the given call. This resource is a list resource and has the common format of list resources. It does not allow for filtering or paging. For more information, see "The Format of List Resources".
The list items are structures with the fields listed in Table 10-5:
Table 10-5 /r/calls/<start_ts>/<end_ts>/<pid>:<id>/vq Fields
| Field | Description |
|---|---|
|
avg_jitter |
Average jitter value for the packets from the RTP stream. |
|
burst_cnt |
The number of sequences of lost RTP packets (gaps). |
|
cid |
Corresponds to the ID of the call the voice quality information belongs to. |
|
decoder |
The codec used by the RTP stream. |
|
dir |
The direction of the RTP stream either 'src2dst' or 'dst2src'. |
|
expected |
Expected number of packets in the RTP stream. |
|
first_ts |
The timestamp of the first measured RTP packet. |
|
Ieeff |
Effective Equipment Impairment Factor. |
|
last_ts |
The timestamp of the last measured RTP packet. |
|
lid |
No meaningful value. |
|
max_burst |
The maximum number of RTP packets lost in sequence (in a single gap). |
|
max_jitter |
The maximum jitter value for the packets from the RTP stream. |
|
MOS |
MOS estimation for voice quality. |
|
pid |
The pid of the call this voice quality information belongs to. |
|
pl_rate |
Packet loss rate for the RTP stream. |
|
R |
R-value score for voice quality. |
|
received |
Received number of packets in the RTP stream. |
|
source |
The source that generated the voice quality information. For example, Operations Monitor. |
|
total_jitter |
Total jitter value for the packets from the RTP stream. |
|
ts |
The timestamp. |
/r/registrations
The list of recent registration events. This resource is a list resource and has the common format of list resources and allows for filtering and paging of the list items. For more information, see "The Format of List Resources".
The list items are structures with the fields listed in Table 10-6:
Table 10-6 /r/registrations Fields
| Field | Description |
|---|---|
|
code |
The response code of the last response to the REGISTER request. |
|
contacts |
The content of the contact header of the REGISTER request. |
|
dest_ip |
The destination IP address of the registration event. |
|
dev_id |
The numeric ID of the platform device that handled the registration event. |
|
device |
The name of the device that handled the registration event. |
|
id |
The unique ID of the registration event. |
|
ip |
The source IP address of the registration event. |
|
realms |
A bitmask of the realms this event belongs to. |
|
ts |
The time stamp of the registration event. |
|
type |
The type of registration event. |
|
type_msg |
Human readable form of the type of registration event. One of New, Failed, Unauthorized, Expired, or Gone. |
|
url |
The url of the full registration event resource. |
|
user |
The identifier of the registered user. |
/r/registrations/<id>
The registration event with the given <id>. This resource is a structure with the fields listed in Table 10-7:
Table 10-7 /r/registrations/<id> Fields
| Field | Description |
|---|---|
|
code |
The response code of the last response to the REGISTER request. |
|
contacts |
The content of the contact header of the REGISTER request. |
|
dest_ip |
The destination IP address of the registration event. |
|
dev_id |
The numeric ID of the platform device that handled the registration event. |
|
device |
The name of the device that handled the registration event. |
|
id |
The unique ID of the registration event. |
|
ip |
The source IP address of the registration event. |
|
messages_url |
The url of the messages resource for this registration event. |
|
realms |
A bitmask of the realms this event belongs to. |
|
type |
The type of registration event. |
|
type_msg |
Human readable form of the type of registration event. One of New, Failed, Unauthorized, Expired, or Gone. |
|
user |
The identifier of the registered user. |
/r/registrations/<id>/messages
The SIP messages belonging to a given registration event. This resource is a list resource and has the common format of list resources and allows paging but not filtering. The list items are exactly like the list items of the /r/calls/<pid>:<id>/messages resource. For more information, see "The Format of List Resources".
/r/devices
The list of configured platform devices. This resource is a list resource and has the common format of list resources. For more information, see "The Format of List Resources".
The list items are structures with the fields listed in Table 10-8:
Table 10-8 /r/devices Fields
| Field | Description |
|---|---|
|
id |
The device ID. |
|
inbound |
The number of inbound calls to this device. |
|
name |
The device name. |
|
outbound |
The number of outbound calls from this device. |
|
url |
The resource url for this device. |
|
users |
The number of registered users at this device. |
/r/devices/<devid>
A representation of the given platform device. This resource is a structure with the fields listed in Table 10-9:
Table 10-9 /r/devices/<devid> Fields
| Field | Description |
|---|---|
|
created_calls_url |
The url to the created_calls resource for this device. |
|
id |
The device ID. |
|
inbound |
The number of inbound calls to this device. |
|
name |
The device name. |
|
outbound |
The number of outbound calls from this device. |
|
registrations_url |
The url to the registrations resource for this device. |
|
relayed_calls_url |
The url to the relayed_calls resource for this device. |
|
terminated_calls_url |
The url to the terminated_calls resource for this device. |
|
users |
The number of registered users at this device. |
/r/devices/<devid>/created_calls
A list of calls created by the given platform device. The format of this resource is exactly like the format of the /calls resource.
/r/devices/<devid>/relayed_calls
A list of calls which are relayed by the given platform device. The format of this resource is exactly like the format of the /calls resource.
/r/devices/<devid>/terminated_calls
A list of calls which are terminated by the given platform device. The format of this resource is exactly like the format of the /calls resource.
/r/devices/<devid>/registrations
A list of registration events handled by the given platform device. The format of this resource is exactly like the format of the /registrations resource.
/r/users/<userid>
Information belonging to a user registered on the monitored platform, similar to the information displayed on the user tracking page. This resource is a structure with the fields listed in Table 10-10:
Table 10-10 /r/users/<userid> Fields
| Field | Description |
|---|---|
|
calls_url |
The url to the calls resource for this user. |
|
current_registrations |
A list containing current registrations of the user. |
|
registrations_url |
The url to the registrations resource for this user. |
|
user |
The user ID. |
The current_registrations field is a list whose list items are structures with the fields listed in Table 10-11:
Table 10-11 current_registrations Fields
| Field | Description |
|---|---|
|
dev_id |
The numeric ID of the platform device that handled the current registrations event. |
|
expires |
The negotiated expiry time of the registration. |
|
expires_in |
The time remaining until registration expiry. |
|
first_seen_ts |
First time the user registered. |
|
last_refreshed_ts |
The last time the user refreshed the registration. |
|
last_seen_ts |
The last time the user registered. |
|
last_suggested_expires |
The value of the expires header of the REGISTER request. |
|
link_quality |
An indication of the quality of the network link between platform and user. |
|
srcip |
The source IP address of the current registrations event. |
|
uri |
The uniform resource identifier (URI) for the current registrations resource. |
|
usrdev |
The name of the device that handled the current registrations event. |
/r/users/<userid>/calls
Calls belonging to the given platform user. The format of this resource is exactly like the format of the /r/calls resource.
/r/users/<userid>/registrations
Registration events belonging to the given platform user. The format of this resource is exactly like the format of the /r/registrations resource.
/r/counters
The list of counters for the admin user and the ALL realm. This resource is a list resource and has the common format of list resources. For more information, see "The Format of List Resources".
The list items are structures with the fields listed in Table 10-12:
Table 10-12 /r/counters Fields
| Field | Description |
|---|---|
|
datatype |
The datatype of the counter. |
|
h_avg |
The average of measurements over one hour. |
|
h_max |
The maximum of measurements over one hour. |
|
h_max |
The maximum of measurements over one hour. |
|
h_sum |
The sum of measurements over one hour. |
|
id |
The numeric counter ID. |
|
m_avg |
The average of measurements over one minute. |
|
m_max |
The maximum of measurements over one minute. |
|
m_min |
The minimum of measurements over one minute. |
|
m_sum |
The sum of measurements over one minute. |
|
maintype |
The numeric counter main type. |
|
name |
The counter name. |
|
p1 |
Counter parameter one. |
|
p2 |
Counter parameter two. |
|
p3 |
Counter parameter three. |
|
subtype |
The numeric counter sub type. |
|
url |
The url to the full counter resource. |
|
value |
The current second measurement. |
/r/counters/<id>
A representation of the given counter. This resource is a structure with the fields listed in Table 10-13:
Table 10-13 /r/counters/<id> Fields
| Field | Description |
|---|---|
|
autoreset |
If the counter is reset every second. |
|
datatype |
The counter datatype. |
|
days |
For average counters, the number of days to average over. |
|
hours_url |
The url to the hours resource for this counter. |
|
id |
The numeric counter ID. |
|
maintype |
The numeric counter main type. |
|
minutes_url |
The url to the minutes resource for this counter. |
|
name |
The name of the counter. |
|
owner |
The owner of the counter: either "system" or "user". |
|
p1 |
Counter parameter one. |
|
p2 |
Counter parameter two. |
|
p3 |
Counter parameter three. |
|
realm |
The realm that this counter belongs to. |
|
seconds_url |
The url to the seconds resource for this counter. |
|
src_cnt |
For average counters, the source counter for the average. |
|
subtype |
The numeric counter sub type. |
|
user_id |
The user ID of the user who owns the counter. |
|
value |
The current second measurement. |
|
weekdays |
For average counters, whether the average is calculated for each weekday separately. |
/r/counters/<id>/seconds
The list of recent second measurements for the given counter. This resource is a list resource and has the common format of list resources and allows paging. The list items are integer values. The list contains up to 3600 values, one value for each of the last 3600 seconds, in chronological order from oldest to youngest. For more information, see "The Format of List Resources".
/r/counters/<id>/minutes
The list of minute values for the given counter. This resource is a list resource and has the common format of list resource and allows paging. The list items are float values. The list contains all the minute averages of the counter measurements stored in the database of Operations Monitor in chronological order from oldest to youngest. For more information, see "The Format of List Resources".
/r/counters/<id>/hours
The list of hour values for the given counter. This resource is a list resource and has the common format of list resources and allows paging. The list items are float values. The list contains all the hour averages of the counter measurements stored in the Operations Monitor database in chronological order from oldest to youngest. For more information, see "The Format of List Resources".
