Manifest API Query Parameters

• Overview
• Filter Parameter
  • Syntax
  • Supported Function
  • Value Requirements
• Pagination Parameters
• Examples
• Error Responses

Overview

The following query parameters are available:

• filter - Narrow the set of resources returned. Required on /groups. Only supported on /groups.
• page[number] and page[size] - Control pagination of results.

Query parameters not listed above are rejected with 400 Bad Request. Each query parameter must not be specified more than once per request.

Filter Parameter

The filter query parameter narrows the set of resources returned. It uses a function-based syntax to specify the filtering behavior and the value to match.

The filter functionality is intentionally limited. The following restrictions apply:

• The filter parameter is supported only on the /groups endpoint.
• The filter parameter is required for requests to /groups. Requests without a filter return 400 Bad Request.
• Only the folder filter function is supported.
• The filter value must begin with an approved namespace prefix and include at least a third-level identifier.
• Only one filter function and one value can be specified per request.

Syntax

The filter query parameter uses the following syntax:

filter=functionName("value")

The value must be enclosed in double quotes. Only one filter function and one value are allowed per request.

Supported Function

Only the folder function is supported.

folder("value")

The function returns groups and nested groups within the supplied folder path value.

The value provided must be a folder path.

Value Requirements

The value supplied to folder function is restricted.

The value:

• must start with one of uw:app:, uw:domain:, uw:org:
• must include at least a third-level identifier
• may include fourth-level and deeper identifiers

Valid:

• uw:org:api
• uw:org:api:admin
• uw:domain:api.wisc.edu
• uw:domain:api.wisc.edu:teams

Invalid:

• uw:org - does not include a third-level identifier.
• invalid:prefix - does not use an approved namespace.

Pagination Parameters

Collection endpoints support pagination using the following query parameters:

• page[number] - The page to return. Defaults to 1.
• page[size] - The number of results per page. Defaults to 100 (the maximum).

Examples

Find all groups under a folder

GET /groups?filter=folder("uw:org:api")

Returns groups and nested groups under the folder path uw:org:api, such as uw:org:api:admin-group, uw:org:api:sub-folder:staff-group, etc.

With pagination

GET /groups?filter=folder("uw:domain:api.wisc.edu")&page[number]=2&page[size]=25

Error Responses

If there is an error in a query parameter, a 400 Bad Request response will be returned with details about the error.

Missing filter parameter

Request: /groups

Response: Query parameter 'filter' is required for this endpoint

Invalid filter syntax

Request: /groups?filter=badSyntax

Response: Syntax error in filter query: ...

Invalid filter value

Request: /groups?filter=folder("invalid:prefix")

Response: Folder value 'invalid:prefix' must start with one of: uw:app:, uw:domain:, uw:org:. ...

Unsupported query parameter

Request: /groups?filter=folder("uw:org:api")&sort=name

Response: Query parameter 'sort' is not available for this endpoint

Duplicate query parameter

Request: /groups?filter=folder("uw:org:api")&filter=folder("uw:org:other")

Response: Query parameter 'filter' must not be specified more than once