Page tree
Skip to end of metadata
Go to start of metadata

 

Introduction

You can use additional parameters to filter UAPI output.

Filter output

UAPI filters use four basic parameters:

parameterTypeDescriptionPossible values
api.filterbooleanWhether to enable filtering.
  • 1 — Enable filtering.
  • 0 — Disable filtering.
api.filter_columnstringThe output parameter to match against.The name of one of the function's parameters.
api.filter_termstringThe value to match.An integer or string value.
api.filter_typestring

The match type.

  • If the api.filter_term value is an integer, use a numeric operator.
  • If the api.filter_term value is a string, use a string operator.

This parameter defaults to contains.

Numeric operators:

  • eq — The column equals to the match value.
  • lt — The column is less than the match value. This match type cannot handle unlimited values.

  • lt_handle_unlimited — The column is less than the match value. This match type can handle unlimited values.

  • gt — The column is greater than the match value. This match type cannot handle unlimited values.
  • gt_handle_unlimited — The column is greater than the match value. This match type can handle unlimited values.
  • ne — The column does not equal to the match value.

    Note:

    We introduced the ne operator in cPanel & WHM version 56.

String operators:

  • contains — The column contains the match value's string. Not case-sensitive.

  • begins The column begins with the match value's string. Not case-sensitive.

  • ends The column ends with the match value's string. Not case-sensitive.

  • matches The column matches the value as a regular expression.

Other operators:

  • defined — The column contains a value.
  • undefined — The column does not contain a value.

    Note:

    We introduced the defined and undefined operators in cPanel & WHM version 58.

 

 

Examples

The following example function calls execute the Email::list_lists function and filter the results to return email accounts with private mailing list archives.

 

/execute/Email/list_lists?api.filter=1&api.filter_column=archive_private&api.filter_term=1&api.filter_type=eq

Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List all of the mailing lists with private archives.
$private_lists = $cpanel->api2(
    'Email', 'list_lists', 
    array(
        'api.filter'          => '1',
        'api.filter_column'   => 'archive_private',
        'api.filter_term'     => '1',
        'api.filter_type'     => 'eq',
    ) 
);

Note:

For more information, read our Guide to the LiveAPI System.

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all of the mailing lists with private archives.
my $private_lists = $cpliveapi->api2(
    'Email', 'list_lists',
    { 
        'api.filter'          => '1',
        'api.filter_column'   => 'archive_private',
        'api.filter_term'     => '1',
        'api.filter_type'     => 'eq',
    }
);

Note:

For more information, read our Guide to the LiveAPI System.

<!-- List all of the mailing lists with private archives. -->
[% execute('Email', 'list_lists', { 'api.filter' => '1', 'api.filter_column' => 'archive_private', 'api.filter_term' => '1', 'api.filter_type' => 'eq', }) %]

Note:

For more information, read our Guide to Template Toolkit documentation. 

{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": [
    {
      "listid": "mylist_example.com",
      "accesstype":"public",
      "desthost": "hostname.example.com",
      "diskused": "17647",
      "humandiskused": "17.23 KB",
      "listadmin":"admin@example.com",
      "list": "mylist@example.com",
      "advertised": "0",
      "archive_private": "1",
      "subscribe_policy": "1"
    }
    {
      "listid": "superlist_example.com",
      "accesstype":"public",
      "desthost": "hostname.example.com",
      "diskused": "90120",
      "humandiskused": "90.12 KB",
      "listadmin":"charlie@example.com",
      "list": "superlist@example.com",
      "advertised": "1",
      "archive_private": "1",
      "subscribe_policy": "1"
    }
    {
      "listid": "list1_example.com",
      "accesstype":"public",
      "desthost": "hostname.example.com",
      "diskused": "16040",
      "humandiskused": "16.04 KB",
      "listadmin":"user@example.com",
      "list": "list1@example.com",
      "advertised": "1",
      "archive_private": "1",
      "subscribe_policy": "1"
    }
  ],
  "metadata": {
    "transformed": 1
  }
}

Use multiple filters

To use multiple filters on a single UAPI call, append an underscore (_) and a number to the end of each filter parameter.

For example, use the following parameters to pass two sets of filter information:

  • Pass the first set of filter information to the api.filter_type_0api_filter_column_0, and api_filter_term_0 parameters.
  • Pass the second set of filter information to the  api.filter_type_1 api_filter_column_1 , and  api_filter_term_1 parameters.

Note:

Do not include more than one api.filter boolean parameter. 

For example, the following examples filter the Email::list_lists function's output to mailing lists that have private archives and do not display on the Mailman directory page.

 

/execute/Email/list_lists?api.filter=1&api.filter_column_0=archive_private&api.filter_term_0=1&api.filter_type_0=eq&api.filter_column_1=advertised&api.filter_term_1=0&api.filter_type_1=eq

Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List all of the mailing lists with private archives that do
// not display on the Mailman directory page.
$very_private_lists = $cpanel->uapi(
    'Email', 'list_lists', 
    array(
        'api.filter'            => '1',
        'api.filter_column_0'   => 'archive_private',
        'api.filter_term_0'     => '1',
        'api.filter_type_0'     => 'eq',
        'api.filter_column_1'   => 'advertised',
        'api.filter_term_1'     => '0',
        'api.filter_type_1'     => 'eq',
    ) 
);

Note:

For more information, read our Guide to the LiveAPI System.

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all of the mailing lists with private archives that do
# not display on the Mailman directory page.
my $very_private_lists = $cpliveapi->uapi(
    'Email', 'list_lists',
    { 
        'api.filter'            => '1',
        'api.filter_column_0'   => 'archive_private',
        'api.filter_term_0'     => '1',
        'api.filter_type_0'     => 'eq',
        'api.filter_column_1'   => 'advertised',
        'api.filter_term_1'     => '0',
        'api.filter_type_1'     => 'eq',
    }
);

Note:

For more information, read our Guide to the LiveAPI System.

<!-- List all of the mailing lists with private archives that do not display on the Mailman directory page. -->
[% execute('Email', 'list_lists', { 'api.filter' => '1', 'api.filter_column_0' => 'archive_private', 'api.filter_term_0' => '1', 'api.filter_type_0' => 'eq','api.filter_column_1' => 'advertised', 'api.filter_term_1' => '0', 'api.filter_type_1' => 'eq', }) %]

Note:

For more information, read our Guide to Template Toolkit documentation. 

{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": [
    {
      "listid": "mylist_example.com",
      "accesstype":"public",
      "desthost": "hostname.example.com",
      "diskused": "17647",
      "humandiskused": "17.23 KB",
      "listadmin":"admin@example.com",
      "list": "mylist@example.com",
      "advertised": "0",
      "archive_private": "1",
      "subscribe_policy": "1"
    }
  ],
  "metadata": {
    "transformed": 1
  }
}