Manifest API Query Parameters
Overview
The following query parameters are available:
filter- Narrow the set of resources returned. Required on/groups. Only supported on/groups.fields- Return only the specified attributes for a resource type. Supported on all/groupsand/membersendpoints. Not supported on/exportsendpoints.page[number]andpage[size]- Control pagination of results.page[after]- Cursor pagination. Only supported on the/groups/{id}member endpoints.
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
filterparameter is supported only on the/groupsendpoint. - The
filterparameter is required for requests to/groups. Requests without afilterreturn400 Bad Request. - Only the
folderfilter 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:apiuw:org:api:adminuw:domain:api.wisc.eduuw:domain:api.wisc.edu:teams
Invalid:
uw:org- does not include a third-level identifier.invalid:prefix- does not use an approved namespace.
Fields Parameter
The fields query parameter limits the attributes returned for each resource to the ones you list. This follows the JSON:API sparse fieldsets specification.
The fields query parameter uses the following syntax:
fields[resourceType]=attribute1,attribute2
The resource id, type, and links are always returned.
Supported resource types and attributes
| Resource type | Attributes |
|---|---|
groups |
path, description |
members |
name, netId, emailAddress |
The following rules apply:
- Attribute names are case-sensitive and use the same names that appear in responses, for example
netId, notnet_id. - An empty value, for example
fields[members]=, returns resources without any attributes. - A
fieldsparameter for a resource type that is not in the response is accepted and has no effect. For example,fields[members]on/groups/{id}does nothing. - The
fieldsparameter is not supported on the/exportsendpoints.
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).
Cursor pagination on group member endpoints
The /groups/{id}/members, /groups/{id}/directMembers, /groups/{id}/indirectMembers, and /groups/{id}/compositeMembers endpoints use cursor pagination by default:
page[after]- The ID of the last member on the previous page. Returns the members that come after it.page[size]- The number of results per page. Defaults to 100 (the maximum).
The links.next link in each response contains the page[after] value for the next page. Follow links.next until it is no longer returned. Cursor pagination does not return a links.prev link.
These endpoints also accept page[number] for offset pagination. When page[number] is passed, the response links use page[number] instead of page[after]. Cursor pagination is recommended because it performs better on large groups.
Only one paging style may be used per request. Passing both page[after] and page[number] returns 400 Bad Request.
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
With cursor pagination
GET /groups/uw:org:api:staff/members?page[size]=25
Then follow links.next, for example:
GET /groups/uw:org:api:staff/members?page[size]=25&page[after]=26b8827a-f050-4558-baea-0fffa88fcde0
Only return group paths
GET /groups?filter=folder("uw:org:api")&fields[groups]=path
Only return NetIDs of group members
GET /groups/uw:org:api:staff/members?fields[members]=netId
Return member names and email addresses
GET /members/26b8827a-f050-4558-baea-0fffa88fcde0?fields[members]=name,emailAddress
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
Invalid fields resource type
Request: /groups/uw:org:api:staff?fields[people]=name
Response: Invalid properties in query parameters - resource type in fields[people] is not a valid resource type.
Invalid fields attribute
Request: /members/26b8827a-f050-4558-baea-0fffa88fcde0?fields[members]=net_id
Response: Invalid properties in query parameters - resource type 'members' doesn't contain the following fields: 'net_id'.
Invalid fields format
Request: /groups/uw:org:api:staff?fields=path
Response: 'fields' query parameter should have the following format - fields[attribute].
Multiple paging styles
Request: /groups/uw:org:api:staff/members?page[after]=26b8827a-f050-4558-baea-0fffa88fcde0&page[number]=2
Response: Multiple paging styles are not allowed. Please use either 'page[after]' or 'page[number]'.