Controlling GET Responses

When you send a GET request to the following resources, you can specify parameters to search, sort, and paginate the JSON data returned in the response:

  • GET /users
  • GET /applications
  • GET /groups

There are three control parameters:

  • search
  • sort
  • page

You can use multiple control parameters in the same API request. See Combine Multiple Control Parameters.

Sort (sort)

Description

Use the sort parameter to sort the list of returned data based on one or more fields. For the list of sortable fields, see Sortable and Searchable Fields.

This parameter performs a case-insensitive sort. For example: both chris and Chris come before Dave.

The resources return a total_available field in the JSON response to provide the total number of user/application/group records that can be returned.

Syntax
  • GET /users/?sort=field
  • GET /applications/?sort=field
  • GET /groups/?sort=field

Where field is the name of the field you want to sort on. This name is case-sensitive; enter it exactly as it appears in the list of Sortable and Searchable Fields.

To sort on multiple fields: Separate multiple fields with commas. Records will be sorted by field1 first; if any of the field1 values are the same, records will then sort by field2.

  • GET /users/?sort=field1,field2
  • GET /applications/?sort=field1,field2
  • GET /groups/?sort=field1,field2

To sort in descending order: By default, the list is sorted in ascending order. To sort in descending order, include a minus sign (-) before the field name.

  • GET /users/?sort=-field
  • GET /applications/?sort=-field
  • GET /groups/?sort=-field

For ascending order, do not include a plus sign (+); it will return an error.

When sorting by multiple fields, you can mix ascending and descending order. For example:

GET /users/?sort=field1,-field2

See the Examples below.

Paginate (page)

Description

By default, EASE returns up to 1000 records. Use the page parameter to specify a starting record and number of records to return. This enables you to retrieve multiple pages. The starting point (or offset) is 0.

For example, use these page parameters for an interface that displays 20 records per page:

  • Page 1: page=0,20 returns records 1 through 20
  • Page 2: page=20,20 returns records 21 through 40
  • Page 3: page=40,20 returns records 41 through 60

You can request more records than are available. EASE will return what is available. For example, if you request 0, 20 users but there are only seven users in the database, EASE will return the first seven users. If you specify a starting record that does not exist, EASE will return 0 records without an error.

The resources return a total_available field in the JSON response to identify the total number of user/application/group records in the database for the organization. This can be used to determine the appropriate UI. For example, if total_available is greater than the number of records returned to you, then you know your application needs to display user interface controls to page through multiple pages.

Syntax
  • GET /users/?page=x,y
  • GET /applications/?page=x,y
  • GET /groups/?page=x,y

Where:

  • x is the starting record
  • y is the total number of records

Combine Multiple Control Parameters

You can specify any combination of control parameters in your request. Use an ampersand (&) to separate parameters. For example, use the following syntax to search for a string and paginate the response:

GET /users/?search=string&?page=\ *x*\,\ *y*\

Note

When using a command line tool, such as curl, to test a GET request, be sure to escape the & (ampersand) with a (backslash).

Examples

Search

  • GET /users/ search example

    This example requests all user records that include the string “Smith” in one of the searchable fields. The total_available field lists the total number of records returned (2, in this example).

    Request

    curl -X GET https://na01ws.apperian.com/v1/users/?search=Smith --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

    Response

    {
      "users": [
        {
          "psk": 118951,
          "first_name": "Sam",
          "last_name": "Smith",
          "modified_date": "2015-12-03T19:21:33.377174+00:00",
          "deleted": null,
          "custom_metadata": {
            "city": "Boston",
            "jobdescription": "design stuff",
            "projects": "Mercury,Gemini",
            "title": "Engineer"
          },
          "email": "ssmith@example.com",
          "mobile_phone": null,
          "role": 1,
          "created_date": "2015-12-03T19:21:33.377174+00:00",
          "until_date": "9999-12-31T23:59:59.999999",
          "disabled_reason": null,
          "id": "sam",
          "last_login_from_catalog": null
        },
        {
          "psk": 103053,
          "first_name": "Kelly",
          "last_name": "Smith",
          "modified_date": "2015-11-13T13:54:13+00:00",
          "deleted": null,
          "custom_metadata": null,
          "email": "ksmith@example.com",
          "mobile_phone": "",
          "role": 1,
          "created_date": "2013-07-24T01:55:32.518310+00:00",
          "until_date": "9999-12-31T23:59:59.999999",
          "disabled_reason": null,
          "id": "exco17",
          "last_login_from_catalog": "2015-11-13T13:54:13.765097"
        }
      ],
      "total_available": 2
  • GET /applications/ search example

    This example requests all application records that include the string “actions” in one of the searchable fields. The total_available field lists the total number of records returned (2, in this example).

    Request

    curl -X GET https://na01ws.apperian.com/v1/applications/?search=actions --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

    Response

    {
      "applications": [
      {
          "display_message": "",
          "operating_system": 103,
          "update_compliance_period_in_days": null,
          "url_scheme": "",
          "form_factor": 2,
          "long_description": "to do",
          "is_adhoc": false,
          "platform": null,
          "is_hybrid": false,
          "required_by": "3099-12-31T00:00:00+00:00",
          "os_version": null,
          "is_app_catalog": false,
          "version": {
            "apperian_wrapper_version": 14,
            "posted_date": "2015-08-12T14:24:40+00:00",
            "unwrapped_version": 49184,
            "description": "[Applied policies] latest",
            "version_num": "1.0",
            "verification_status": 0,
            "veracode_verification_id": null,
            "release_date": "2015-08-12T14:24:40+00:00",
            "expires": "9999-12-31T23:59:59.999999",
            "mdm_id": null,
            "required": false,
            "required_by": "9999-12-31T23:59:59.999999",
            "mdm_status": 0,
            "verification_id": null,
            "psk": 50173,
            "checksum": "eb25f65bf4cf9029da387c0e91c5eddda75ad5f728983bfa5cb830839e3769ad",
            "app_psk": 21132,
            "wrap_status": 1,
          "signstatus": 1,
            "veracode_verification_status": 0,
            "notify_users": true
          },
          "short_description": "to do",
          "screenshot_path3": "",
          "screenshot_path1": "",
          "type": 3,
          "screenshot_path4": "",
          "screenshot_path5": "",
          "status": 0,
          "psk": 21132,
          "sort_weight": 1000,
        "no_auth_delivery_enabled": false,
          "deleted": null,
          "icon_path": "org_1062/android_21132/appicon.png",
          "is_email_config_profile": false,
          "custom_metadata": null,
          "add_to_start": false,
          "screenshot_path2": "",
          "tablet_screenshot_path5": "",
        "min_os_version": "11",
          "bundle_id": "com.apperian.demo.actions",
          "banner_image_url": null,
          "categories": [],
          "tablet_screenshot_path3": "",
          "tablet_screenshot_path4": "",
          "tablet_screenshot_path2": "",
          "name": "Actions",
          "tablet_screenshot_path1": "",
          "direct_download_binary_url": "https://na01ws.apperian.com/v1/downloads/direct/applications/8tdUaee22I2u9JA3cvX0sA",
          "required": false,
          "push_enabled": false
        },
        {
          "display_message": "",
          "operating_system": 1,
          "update_compliance_period_in_days": null,
          "url_scheme": "eas16653",
          "form_factor": 3,
          "long_description": "Come on...get organized. You can do it!",
          "is_adhoc": false,
          "platform": null,
          "is_hybrid": false,
          "required_by": "9999-12-31T23:59:59.999999",
          "os_version": null,
          "is_app_catalog": false,
          "version": {
            "apperian_wrapper_version": null,
            "posted_date": "2015-06-17T00:32:00.581760+00:00",
            "unwrapped_version": 38560,
            "description": "[Removed policies] latest",
            "version_num": "3.0",
            "verification_status": 0,
            "veracode_verification_id": null,
            "release_date": "2015-06-17T00:32:00.581760+00:00",
            "expires": "2015-09-04T19:14:14+00:00",
            "mdm_id": null,
            "required": false,
            "required_by": "9999-12-31T23:59:59.999999",
            "mdm_status": 0,
            "verification_id": null,
            "psk": 48777,
            "checksum": "f6d701138b2771405399ac5281bdde018f86e3d46dfd49280e42f7a3b348aed8",
            "app_psk": 16653,
            "wrap_status": 0,
            "signstatus": 1,
            "veracode_verification_status": 0,
            "notify_users": true
          },
          "short_description": "Manage your TO DO list",
          "screenshot_path3": "",
          "screenshot_path1": "",
          "type": 0,
          "screenshot_path4": "",
          "screenshot_path5": "",
          "status": 0,
          "psk": 16653,
          "sort_weight": 1000,
          "no_auth_delivery_enabled": false,
          "deleted": null,
          "icon_path": "org_1062/iphone_16653/Actions_57.png",
          "is_email_config_profile": false,
          "custom_metadata": null,
          "add_to_start": false,
          "screenshot_path2": "",
          "tablet_screenshot_path5": "",
          "min_os_version": "3.1",
          "bundle_id": "com.apperian.Actions",
          "banner_image_url": null,
          "categories": [
            {
              "psk": 24174,
              "org_psk": 1062,
              "constant": "HR",
              "name": "Human Resources",
              "icon_path": "/icons/categories/human_Resources.png",
              "description": ""
            }
          ],
          "tablet_screenshot_path3": "",
          "tablet_screenshot_path4": "",
          "tablet_screenshot_path2": "",
          "name": "Actions APP USAGE",
          "tablet_screenshot_path1": "",
          "direct_download_binary_url": "https://na01ws.apperian.com/v1/downloads/direct/applications/zBtnxnHyWlHAAF8RnBkTWQ",
    "required": false,
    "push_enabled": false
        },
      ],
      "total_available": 2
  • GET /groups/ search example

    This example requests all application records that include the string “sales” in one of the searchable fields. The total_available field lists the total number of records returned (3, in this example).

    Request

    curl -X GET https://na01ws.apperian.com/v1/groups/?search=sales --header "X-TOKEN:uCilExLSSC6qJr41UkIKYw"

    Response

    {
      "total_available": 3,
      "groups": [
        {
          "app_count": 4,
          "psk": 1198,
          "user_count": 11,
          "name": "Sales",
          "description": "cat 1"
        },
        {
          "app_count": 0,
          "psk": 9298,
          "user_count": 0,
          "name": "Worldwide Sales",
          "description": "Worldwide Sales team"
        },
        {
          "app_count": 0,
          "psk": 9299,
          "user_count": 0,
          "name": "Northeast Sales",
          "description": "Northeast Sales team"
        }
      ]
    }
    
  • GET /users/ search on custom metadata example

    This example requests all user records that include the string “Boston” in a custom metadata field named location. The total_available field lists the total number of records returned (2, in this example).

    Request

    curl -X GET https://na01ws.apperian.com/v1/users/?search=location:Boston --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

    Response

    {
      "users": [
        {
          "status": "invited",
          "psk": 127131,
          "first_name": "Taylor",
          "last_name": "Burns",
          "modified_date": "2016-02-04T13:40:43+00:00",
          "deleted": null,
          "custom_metadata": {
            "description": "Software Engineer",
            "location": "Boston",
            "projects": [
              "Mercury"
            ],
            "title": "Senior Software Engineer"
          },
          "email": "taylorburns@example.com",
          "disabled": false,
          "role_name": "User",
          "role": 1,
          "created_date": "2016-02-04T13:40:43+00:00",
          "until_date": "9999-12-31T23:59:59.999999",
          "mobile_phone": "",
          "disabled_reason": null,
          "id": "taylerburns",
          "last_login_from_catalog": null
        },
        {
          "status": "invited",
          "psk": 127115,
          "first_name": "Harry",
          "last_name": "Bergeron",
          "modified_date": "2016-02-04T13:40:42+00:00",
          "deleted": null,
          "custom_metadata": {
            "description": "Northeast Sales Manager",
            "location": "Boston",
            "projects": [
              "Gemini"
            ],
            "title": "Sales Manager"
          },
          "email": "hbergeron@example.com",
          "disabled": false,
          "role_name": "User",
          "role": 1,
          "created_date": "2016-02-04T13:40:42+00:00",
          "until_date": "9999-12-31T23:59:59.999999",
          "mobile_phone": "",
          "disabled_reason": null,
          "id": "hbergeron",
          "last_login_from_catalog": null
        }
      ],
      "total_available": 2
    }
    

Sort and Paginate

  • GET /users/ sort and paginate example

    This example returns user records 0 through 3 and sorts them by last_name in ascending order. Notice that in this curl command syntax, the & (ampersand) is escaped by a (backslash). The total_available field lists the total number of user records in the authenticated user’s organization (72, in this example).

    Request

    curl -X GET https://na01ws.apperian.com/v1/users/?sort=last_name\&page=0,3 --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

    Response

    {
      "users": [
        {
          "psk": 23301,
          "first_name": "Bob",
          "last_name": "Alexander",
          "modified_date": "2012-06-26T18:51:14+00:00",
          "deleted": null,
          "custom_metadata": null,
          "email": "ba@example.com",
          "mobile_phone": null,
          "role": 1,
          "created_date": "2012-06-26T18:51:14+00:00",
          "until_date": "9999-12-31T23:59:59.999999",
          "disabled_reason": null,
          "id": "ba@example.com",
          "last_login_from_catalog": null
        },
        {
          "psk": 118504,
          "first_name": "Alfred",
          "last_name": "Alfresco",
          "modified_date": "2015-11-03T12:42:22.002882+00:00",
          "deleted": null,
          "custom_metadata": null,
          "email": "aalfresco@example.com",
          "mobile_phone": "",
          "role": 1,
          "created_date": "2015-11-03T12:42:22.002882+00:00",
          "until_date": "2015-12-14T14:36:23.392807+00:00",
          "disabled_reason": 2,
          "id": "alfred",
          "last_login_from_catalog": "2015-11-03T12:46:28.490078"
        },
        {
          "psk": 106438,
          "first_name": "Alberto",
          "last_name": "Arias",
          "modified_date": "2014-03-25T13:43:03+00:00",
          "deleted": null,
          "custom_metadata": null,
          "email": "aarias@example.com",
          "mobile_phone": "1234567890",
          "role": 1,
          "created_date": "2014-03-25T13:41:05+00:00",
          "until_date": "9999-12-31T23:59:59.999999",
          "disabled_reason": null,
          "id": "alberto",
          "last_login_from_catalog": "2014-11-18T13:59:34.374598"
        }
      ],
      "total_available": 72
    }
    

Search and Paginate

  • GET /applications/ search and paginate example

    This example searches for applications that include the string “directory” in the searchable fields and returns records 0 through 3. Notice that in this curl command syntax, the & (ampersand) is escaped by a (backslash). The total_available field lists the total number of application records that meet the search criteria (10, in this example).

    Request

    curl -X GET https://na01ws.apperian.com/v1/users/?search=directory\&page=0,3 --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

    Response

    {
      "applications": [
        {
          "display_message": "",
          "operating_system": 103,
          "update_compliance_period_in_days": 7,
          "url_scheme": "",
          "form_factor": 2,
          "long_description": "Corporate Directory",
          "is_adhoc": false,
          "platform": null,
          "is_hybrid": false,
          "required_by": "2013-06-26T00:00:00+00:00",
          "os_version": null,
          "is_app_catalog": false,
          "version": {
            "apperian_wrapper_version": 9,
            "posted_date": "2014-12-04T13:33:54+00:00",
            "unwrapped_version": 8626,
            "description": "[Applied policies] Updated to cover worldwide offices.",
            "version_num": "1.0,16",
            "verification_status": 0,
            "veracode_verification_id": null,
            "release_date": "2014-12-04T13:33:54+00:00",
            "expires": "9999-12-31T23:59:59.999999",
            "mdm_id": null,
            "required": false,
            "required_by": "9999-12-31T23:59:59.999999",
            "mdm_status": 0,
            "verification_id": null,
            "psk": 42924,
            "checksum": "2ddbba3d5e5f736afaa577de6da9a48c09963b7048cf66a393ed4960242558b8",
            "app_psk": 4758,
            "wrap_status": 1,
            "signstatus": 1,
            "veracode_verification_status": 0,
            "notify_users": true
          },
          "short_description": "Corporate Directory",
          "screenshot_path3": "",
          "screenshot_path1": "",
          "type": 3,
          "screenshot_path4": "",
          "screenshot_path5": "",
          "status": 1,
          "psk": 4758,
          "sort_weight": 1000,
          "no_auth_delivery_enabled": true,
          "deleted": null,
          "icon_path": "org_1062/android_4758/appicon.png",
          "is_email_config_profile": false,
          "custom_metadata": null,
          "add_to_start": false,
          "screenshot_path2": "",
          "tablet_screenshot_path5": "",
          "min_os_version": "11",
          "bundle_id": "com.apperian.demo.directory",
          "banner_image_url": null,
          "categories": [],
          "tablet_screenshot_path3": "",
          "tablet_screenshot_path4": "",
          "tablet_screenshot_path2": "",
          "name": "Directory",
          "tablet_screenshot_path1": "",
          "direct_download_binary_url": "https://ws-qaease.qa.apperian.com/v1/downloads/direct/applications/EWWinYlbohK1tEV4ZoD8Bw",
          "required": false,
          "push_enabled": false
        },
        {
          "display_message": "",
          "operating_system": 103,
          "update_compliance_period_in_days": null,
          "url_scheme": "",
          "form_factor": 2,
          "long_description": "test categories",
          "is_adhoc": false,
          "platform": null,
          "is_hybrid": false,
          "required_by": "3099-12-31T00:00:00+00:00",
          "os_version": null,
          "is_app_catalog": false,
          "version": {
            "apperian_wrapper_version": null,
            "posted_date": "2016-01-08T13:45:37.676019+00:00",
            "unwrapped_version": 63251,
            "description": "latest",
            "version_num": "1.0",
            "verification_status": 0,
            "veracode_verification_id": null,
            "release_date": "2016-01-08T13:45:37.676019+00:00",
            "expires": "9999-12-31T23:59:59.999999",
            "mdm_id": null,
            "required": false,
            "required_by": "9999-12-31T23:59:59.999999",
            "mdm_status": 0,
            "verification_id": null,
            "psk": 63251,
            "checksum": "7199719ccdf7e922576390f6a9e86258b302a8a3bc14635af6998b46a96facbc",
            "app_psk": 23643,
            "wrap_status": 0,
            "signstatus": 0,
            "veracode_verification_status": 0,
            "notify_users": false
          },
          "short_description": "test categories",
          "screenshot_path3": "",
          "screenshot_path1": "",
          "type": 3,
          "screenshot_path4": "",
          "screenshot_path5": "",
          "status": 1,
          "psk": 23643,
          "sort_weight": 1000,
          "no_auth_delivery_enabled": false,
          "deleted": null,
          "icon_path": "org_1062/android_23643/appicon.png",
          "is_email_config_profile": false,
          "custom_metadata": {
            "school": "default value",
            "major": "default value",
            "year": "Sophomore"
          },
          "add_to_start": false,
          "screenshot_path2": "",
          "tablet_screenshot_path5": "",
          "min_os_version": "11",
          "bundle_id": "com.apperian.demo.directory",
          "banner_image_url": null,
          "categories": [],
          "tablet_screenshot_path3": "",
          "tablet_screenshot_path4": "",
          "tablet_screenshot_path2": "",
          "name": "Directory",
          "tablet_screenshot_path1": "",
          "direct_download_binary_url": "https://ws-qaease.qa.apperian.com/v1/downloads/direct/applications/BH1Etxp4vqFbe6nLquFisg",
          "required": false,
          "push_enabled": false
        }
      ],
      "total_available": 10
    }
    

Sortable and Searchable Fields

The following table lists the fields that you can sort and search on when sending a request to the GET /users or GET /applications resources.

Resource Sortable Fields Searchable Fields
GET /users
  • first_name
  • last_name
  • created_date
  • modified_date
  • last_login_from_catalog
  • role
  • status
  • first_name
  • last_name
  • mobile_phone
  • id (This is the user’s User ID)
  • email
  • custom_metadata_field
GET /applications
  • name
  • bundle_id
  • sort_weight
  • name
  • short_description
  • long_description
  • custom_metadata_field
GET /groups
  • name
  • description
  • name
  • description

Note

When you search on a user or application custom metadata field, the field name is case sensitive; be sure to specify the name exactly as it appears when you list application data (with GET /applications or GET /applications/<app_psk>) or user data (with GET /users or GET /users/<user_psk>).