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

 

Introduction

You can use additional parameters to sort UAPI output.

Sort output

UAPI sorting uses four basic parameters:

parameterTypeDescriptionPossible values
api.sort BooleanWhether to enable sorting.
  • 1 — Enable sorting.
  • 0 — Disable sorting.
api.sort_columnstringThe return to sort by.The name of one of the function's returns.
api.sort_methodstring

The type of sorting to use.

This parameter defaults to lexicographic.

Warning:

You must set this parameter whenever you sort numeric values, or the function will fail. 

  • ipv4 — Sort output by the numeric value of each octet in an IPv4 address.
  • numeric — Sort output in numeric order, with 0 as the lowest number.
  • numeric_zero_as_max — Sort output in numeric order, with 0 as the highest number.
  • lexicographic — Sort output in alphabetical order.
api.sort_reverseBoolean

Whether to sort data in reverse order.

  • 1 — Sort in reverse order.
  • 0 — Do not sort in reverse order.

Examples

The following example function calls execute the Email::list_lists function and use the numeric method to sort the diskused parameter's values in reverse order.

/execute/Email/list_lists?api.sort=1&api.sort_column=diskused&api.sort_method=numeric&api.sort_reverse=0

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 by the amount of disk they use.
$list_by_disk = $cpanel->api2(
    'Email', 'list_lists', 
    array(
        'api.sort'          => '1',
        'api.sort_column'   => 'diskused',
        'api.sort_method'   => 'numeric',
        'api.sort_reverse'  => '0',
    ) 
);

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 by the amount of disk they use.
my $list_by_disk = $cpliveapi->api2(
    'Email', 'list_lists',
    { 
        'api.sort'          => '1',
        'api.sort_column'   => 'diskused',
        'api.sort_method'   => 'numeric',
        'api.sort_reverse'  => '0',
    }
);

Note:

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

<!-- List all of the mailing lists by the amount of disk they use. -->
[% execute('Email', 'list_lists', { 'api.sort' => '1', 'api.sort_column' => 'diskused', 'api.sort_method' => 'numeric', 'api.sort_reverse' => '0', }) %]

Note:

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

uapi --user=username Email list_lists api.sort=1 api.sort_column=diskused api.sort_method=numeric api.sort_reverse=0
{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": [
    {
      "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"
    }
    {
      "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"
    }
  ],
  "metadata": {
    "transformed": 1
  }
}

Use multiple sorts

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

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

  • Pass the first set of sorting information to the api.sort_method_0api_sort_column_0, and api_sort_reverse_0 parameters.
  • Pass the second set of sorting information to the  api.sort_method_1 api_sort_column_1 , and  api_sort_reverse_1 parameters.

Note:

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

For example, the following examples sort the Email::list_lists function's output by whether they appear on the Mailman directory page and then their list name in reverse alphabetical order.

/execute/Email/list_lists?api.sort=1&api.sort_column_0=advertised&api.sort_method=numeric&api.sort_reverse_0=0&api.sort_column_1=list&api.sort_method_1=lexicographic&api.sort_reverse_1=1

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 sorted by whether they are displayed
// on the Mailman directory, and then by name in reverse alphabetical order
$very_private_lists = $cpanel->uapi(
    'Email', 'list_lists', 
    array(
        'api.sort'            => '1',
        'api.sort_column_0'   => 'advertised',
        'api.sort_method_0'     => 'numeric',
        'api.sort_type_0'     => '0',
        'api.sort_column_1'   => 'list',
        'api.sort_method_1'     => 'lexicographic',
        'api.sort_type_1'     => '1',
    ) 
);

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 sorted by whether they are displayed
// on the Mailman directory, and then by name in reverse alphabetical order
my $very_private_lists = $cpliveapi->uapi(
    'Email', 'list_lists',
    { 
        'api.sort'            => '1',
        'api.sort_column_0'   => 'advertised',
        'api.sort_method_0'     => 'numeric',
        'api.sort_type_0'     => '0',
        'api.sort_column_1'   => 'list',
        'api.sort_method_1'     => 'lexicographic',
        'api.sort_type_1'     => '1',
    }
);

Note:

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

<!-- List all of the mailing lists sorted by whether they are displayed on the Mailman directory, and then by name in reverse alphabetical order. -->
[% execute('Email', 'list_lists', { 'api.sort' => '1', 'api.sort_column_0' => 'advertised', 'api.sort_method_0' => 'numeric', 'api.sort_reverse_0' => '0','api.sort_column_1' => 'list', 'api.sort_method_1' => 'lexicographic', 'api.sort_reverse_1' => '1', }) %]

Note:

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

uapi --user=username Email list_lists api.sort=1 api.sort_column_0=diskused api.sort_method_0=numeric api.sort_reverse_0=0 api.sort_column_1=list api.sort_method_1=lexicographic api.sort_reverse_1=1
{  
   "data":[  
      {  
         "subscribe_policy":3,
         "listadmin":"user@example.com",
         "humandiskused":"20.45 KB",
         "desthost":"example.com",
         "archive_private":1,
         "accesstype":"private",
         "advertised":0,
         "diskused":"20942",
         "list":"worldleaders@example.com",
         "listid":"worldleaders_example.com"
      },
      {  
         "list":"talkshows@example.com",
         "diskused":"20920",
         "advertised":0,
         "listid":"talkshows_example.com",
         "desthost":"example.com",
         "humandiskused":"20.43 KB",
         "subscribe_policy":3,
         "listadmin":"user@example.com",
         "accesstype":"private",
         "archive_private":1
      },
      {  
         "listadmin":"user@example.com",
         "subscribe_policy":3,
         "desthost":"example.com",
         "humandiskused":"20.46 KB",
         "archive_private":1,
         "accesstype":"private",
         "advertised":0,
         "diskused":"20956",
         "list":"campaigndonors@example.com",
         "listid":"campaigndonors_example.com"
      },
      {  
         "archive_private":0,
         "accesstype":"public",
         "subscribe_policy":1,
         "listadmin":"user@example.com",
         "humandiskused":"20.52 KB",
         "desthost":"example.com",
         "listid":"statedepartment_example.com",
         "advertised":1,
         "diskused":"21010",
         "list":"statedepartment@example.com"
      },
      {  
         "listid":"foundationemployees_example.com",
         "advertised":1,
         "diskused":"20990",
         "list":"foundationemployees@example.com",
         "archive_private":0,
         "accesstype":"public",
         "listadmin":"user@example.com",
         "subscribe_policy":1,
         "humandiskused":"20.5 KB",
         "desthost":"example.com"
      }
   ],
   "metadata":{  
      "transformed":1
   },
   "messages":null,
   "errors":null,
   "status":1
}