Skip to content

List and search calls

Get a list of all calls:

GET /api/v2/calls.json

Example of JSON response:

{  
    "next_url": null,
    "calls":[{
        "call_id": "e03f497d-bdff-1019-102b-f5caab54f081",
        "setup_time": "2013-10-12T16:32:22-0800"
        "from_number": "102",
        "to_number": "101",
        ...
    },{
        "call_id": "e03f497d-bdff-1019-1023-694f40413c84",
        "setup_time": "2013-10-12T18:45:02-0800"
        "from_number": "103",
        "to_number": "105",
         ...
    }]
}

Paging

Each response has next_url attribute like:

{
    "calls": [ ... ],
    "next_url": "/api/v2/calls.json?start=200"
 }

next_url is set to null if there are no more pages. Otherwise the client application should use this URL to sent retrieve next portion of records.

When requesting a list of objects, by default MiaRec returns 20 records per page. The client application may request up to 1000 items per page with URI parameter limit=X, for example:

/api/v2/calls.json?limit=500

Calculating a total number of records

A calculation of a total number of records matching to the search criteria can be very expensive operation. For optimization purposes, the MiaRec application doesn't calculate such value. The next_url attribute is used to signal if more data is available beyond the currently requested page. On the very last page, the application sets next_url attribute to null and includes the total attribute, which is equal to a total number of records of all pages.

The following example represents the last page of data, i.e. no more data is available:

{
    "calls": [ ... ],
    "next_url": null,
    "total": 513
 }

How does the application know that there is more data available beyond the current page?

It is quite easy. The application queries the database for limit+1 records. The last records, if available, is discarded, i.e. the application always returns up to limit records. A presence of the last record is a signal that more data is available beyond the currently requested page. Yet, it is not known if there is only 1 extra record available or a lot more.

The MiaRec web portal uses one trick to improve user experience when paginating data.

It shows a pagination counter like "0-20 of many" to signal that more data is available. Word "many" means that there are more than 1,000 records available beyond the current page, otherwise, it shows the pagination counter like "0-20 of 893" telling the end user that only 893 records are available in database. How does it do that?

Actually, the MiaRec web portal queries 1,000 records instead of the page size (limit attribute). For example, when end user wants to see the first 20 records, the application actually queries 1,000 records. It calculates a total number of the returned records. If it is less than 1,000, then it shows that exact number to end user (for example, 0-20 of 813), otherwise it shows "many" word telling that a lot more records are available (more than 1,000).

To replicate the same user experience in your application, you can pass the URI parameter max_total_calc to REST API. If max_total_calc is set to 1,000, then the application queries 1,000 records even if limit is set, for example, to 50.

A response still contains 50 or less records, but the total attribute will be set to a non-null value no more than 1,000 records available beyond the current page.

Note, for performance reasons, a maximum accepted value for max_total_calc parameter is limited to 1,000.

Example request:

/api/v2/calls.json?limit=50&max_total_calc=1000

Response:

{
    "calls": [ ... ],
    "next_url": "/api/v2/calls.json?start=50&limit=50&max_total_calc=1000"
    "total": 813
 }

In this example, the total attribute signals that only 813 records are available in DB (less than 1,000 beyond the currently requested page 0-50). Note, the next_url attribute is not null, i.e. more pages are available beyond page 0-50.

The returned list of objects may be filtered to narrow the search results according to different attributes, like date range, user, group, search term etc.

Filtering parameters should be specified as URI parameters.

REST API supports two search engines:

  • Basic search
  • Advanced search

The Basic search supports filtering recordings by the most frequently used attributes.

The Advanced search supports more attributes for searching as well as various comparison operators like "ends with", "is empty", etc. This search capability is the same as available in the MiaRec web portal on the Advanced Search tab.

CHILD PAGES