10 REST API
This chapter describes how to work with the Oracle Communications Operations Monitor REST API.
A simple REST API facilitates access to much of the information generated by Operations Monitor.
REST is a way of implementing Remote Procedure Call (RPC) systems on top of HTTP. REST APIs are stateless, since they don't use mechanisms of application state keeping that are traditionally employed together with HTTP, such as cookies or sessions. Everything necessary for keeping the application state must be encoded into the HTTP requests. REST APIs are structured around addressable resources, that means all information, that is provided or manipulated by the API, is addressable with HTTP URLs. Conceptually, resources are like the files and directories of a file system, organized into a tree of parents and children.
From the generally used HTTP methods GET, POST, PUT, and DELETE, Operations Monitor's REST API only uses the GET method, as the interface is intended to only query information from Operations Monitor.
Note:
The remote application needs to authenticate itself with the administrator password over the standard HTTP Basic mechanism.
Note:
REST API searches are not guaranteed to be real-time without advanced hardware sizing. Continuous REST API searches or queries to Oracle Communications Operations Monitor may impact its performance, potentially causing UI slowness, slower REST API response times.
Example call:
$ curl -L -u admin:<passwd> https://10.1.0.81/r/users/00493077715680/calls/recent
{"data": [
{"state_msg": "Finished",
"code": 200,
"dst_codecs": "PCMU,PCMA,iLBC,telephone-event",
"src_codecs": "PCMU,PCMA,telephone-event,iLBC",
"pid": 1250018007,
"url": "\/r\/users\/00493077715680\/calls\/1250018007:16739",
[...]
}
[...]
]}Note:
Oracle recommends to replace the self-signed certificate delivered with the software with a certificate signed by a certificate authority. If you are using self-signed certificate, it is possible that the connection fails as the certificate could not be verified. You have to either install the certificate of the signing CA or provide a method to use the tool directly.
For curl, you could pass the certificate as follows:
curl --cacert <file with the certificate> -L -u admin:<passwd> https://10.1.0.81/r/users/00493077715680/calls/recent
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".
The Format of List Resources
List resources like the /r/calls/recent resource are structures with the fields listed in Table 10-14:
Table 10-14 List Resources Fields
| Field | Description |
|---|---|
|
data |
The actual list. The format of the list item depends on the resource. |
|
limit |
The number of returned items. |
|
start |
The index of the first returned item. |
|
total |
The total number of items that exist. |
All list resources allow paging. Paging is enabled by default and can be controlled by giving the start and limit GET parameters when requesting the resource. The start parameter gives the index of the first item to be returned, the limit parameter gives the number of items to be returned.
Note, that limit cannot exceed the value given in the vsp.rest.max_limit system setting and is adjusted if it does exceed this value. For the counter seconds, minutes and hours resource you can also give start_ts instead of start, meaning that the request will only return items with an associated timestamp that is greater or equal than the given timestamp.
Some list resources also allow filtering. Filtering is controlled by additional GET request parameters. A filter controlling parameter must have the form <fieldname>_<verb>, where <fieldname> is the name of a field of the list items of the resource and <verb> determines the logic of the filter. The known verbs and their meaning are listed in Table 10-15:
Table 10-15 List Resources Verbs
| Verb | Description |
|---|---|
|
contains |
This filter applies if the set valued field contains the set given. The parameter must be given as a list separated by '+'. |
|
deq |
This filter applies if the date contained in the field and the given date are equal. The date must be given as "mm/dd/yyyy", where mm is the month, dd the day of the month and yyyy the year. |
|
dgeq |
This filter applies if the date contained in the field is younger or equal to the given date. The date must be given as "mm/dd/yyyy", where mm is the month, dd the day of the month and yyyy the year. |
|
dgt |
This filter applies if the date contained in the field is younger than the date given in the parameter. The date must be given as "mm/dd/yyyy", where mm is the month, dd the day of the month and yyyy the year. |
|
dleq |
This filter applies if the date contained in the field is older or equal to the given date. The date must be given as "mm/dd/yyyy", where mm is the month, dd the day of the month and yyyy the year. |
|
dlt |
This filter applies if the date contained in the field is older. The date must be given as "mm/dd/yyyy", where mm is the month, dd the day of the month and yyyy the year. |
|
dteq |
This filter applies if the date and time contained in the field is equal to the date and time given. The date and time must be given as "yyyy/mm/dd HH:MM:SS", where yyyy is the year, mm the month, dd the day of the month, HH the hour, MM the minute and SS the second. |
|
dtgeq |
This filter applies if the date and time contained in the field is younger or equal to the date and time given. The date and time must be given as "yyyy/mm/dd HH:MM:SS", where yyyy is the year, mm the month, dd the day of the month, HH the hour, MM the minute and SS the second. |
|
dtgt |
This filter applies if the date and time contained in the field is younger than the date and time given in the parameter. The date and time must be given as "yyyy/mm/dd HH:MM:SS", where yyyy is the year, mm the month, dd the day of the month, HH the hour, MM the minute and SS the second. |
|
dtleq |
This filter applies if the date and time contained in the field is older or equal to the date and time given. The date and time must be given as "yyyy/mm/dd HH:MM:SS", where yyyy is the year, mm the month, dd the day of the month, HH the hour, MM the minute and SS the second. |
|
dtlt |
This filter applies if the date and time contained in the field is older than the given date and time. The date and time must be given as "yyyy/mm/dd HH:MM:SS", where yyyy is the year, mm the month, dd the day of the month, HH the hour, MM the minute and SS the second. |
|
eq |
This filter applies if the numeric value contained in the field is equal to the number given. |
|
geq |
This filter applies if the numeric value contained in the field is greater than or equal to the number given. |
|
gt |
This filter applies if the numeric value contained in the field is greater than the numeric value given in the parameter. |
|
leq |
This filter applies if the numeric value contained in the field is smaller than or equal to the number given. |
|
lt |
This filter applies if the numeric value contained in the field is smaller than the number given. |
|
oneof |
This filter applies if the value contained in the field is equal to one of the values given. The values must be given as a list separated by '+'. |
|
substr |
This filter applies if the value of the parameter is contained in the field. |
In case the GET request parameters cannot be parsed, an HTTP 400 Bad Request status code is returned.