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.

Search (`search`)¶

Description

Use the search parameter to return only the data records that meet the search criteria. You can search on text fields only, not dates or integers. For the list of searchable fields, see Sortable and Searchable Fields. You can also search on custom metadata fields; to do this, you need to include the custom metadata field name before the string (custom_metadata_field:string).

This parameter performs a case-insensitive, substring search that returns all records containing the string in the searchable field. You cannot search for exact matches, or search for only values that begin or end with the specified string.

The resources return a total_available field in the JSON response to provide the total number of user/application/group records that meet the search criteria.

Syntax

GET /users/?search=string
GET /applications/?search=string
GET /groups/?search=string
GET /groups/?search=custom_metadata_field:string

See the Examples below.

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, Apperian 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. Apperian will return what is available. For example, if you request 0, 20 users but there are only seven users in the database, Apperian will return the first seven users. If you specify a starting record that does not exist, Apperian 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,
      "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",
        "required": false,
        "required_by": "9999-12-31T23:59:59.999999",
        "verification_id": null,
        "psk": 50173,
        "checksum": "eb25f65bf4cf9029da387c0e91c5eddda75ad5f728983bfa5cb830839e3769ad",
        "app_psk": 21132,
        "wrap_status": 1,
      "signstatus": 1,
        "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",
      "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,
      "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",
        "required": false,
        "required_by": "9999-12-31T23:59:59.999999",
        "verification_id": null,
        "psk": 48777,
        "checksum": "f6d701138b2771405399ac5281bdde018f86e3d46dfd49280e42f7a3b348aed8",
        "app_psk": 16653,
        "wrap_status": 0,
        "signstatus": 1,
        "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",
      "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,
      "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",
        "required": false,
        "required_by": "9999-12-31T23:59:59.999999",
        "verification_id": null,
        "psk": 42924,
        "checksum": "2ddbba3d5e5f736afaa577de6da9a48c09963b7048cf66a393ed4960242558b8",
        "app_psk": 4758,
        "wrap_status": 1,
        "signstatus": 1,
        "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",
      "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://na01ws.apperian.com/v1/downloads/direct/applications/EWWinYlbohK1tEV4ZoD8Bw",
      "required": false,
      "push_enabled": false
    },
    {
      "display_message": "",
      "operating_system": 103,
      "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",
        "required": false,
        "required_by": "9999-12-31T23:59:59.999999",
        "verification_id": null,
        "psk": 63251,
        "checksum": "7199719ccdf7e922576390f6a9e86258b302a8a3bc14635af6998b46a96facbc",
        "app_psk": 23643,
        "wrap_status": 0,
        "signstatus": 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",
      "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://na01ws.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 specific 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
GET /catalog/applications	bundle_id name sort_weight release_date

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>).

Controlling GET Responses¶

Search (search)¶

Sort (sort)¶

Paginate (page)¶

Combine Multiple Control Parameters¶

Examples¶

Sortable and Searchable Fields¶

Search (`search`)¶

Sort (`sort`)¶

Paginate (`page`)¶