Query Parameters
You can include query parameters in requests to the Oracle Identity Cloud Service REST APIs. These parameters are useful for finding resources with specific attributes or attribute values, and for sorting and paginating the output.
About Query Parameters
Using a query, you can filter the output:
Note:
Query filtering capabilities depend on the REST service. Some REST services may (without SCIM) not support the advanced filtering and parameters that you want to use.-
List only resources containing specified attributes or having specified values for attributes.
-
Limit the attributes returned in the response body.
-
Sort the output on a specified attribute, in ascending or descending order.
-
Limit the number of resources returned.
-
Specify where, in the list of resources in the collection, to start the request.
-
GET: For filtering search results. See Query Parameters With GET.
-
POST: For filtering search results using the parameters in the Request body (for security reasons). See Query Parameters With a POST /.search Request Body.
Query Parameters With GET
GET
request on a resource endpoint such as
/Users
or
/Groups,
you put the query in the URL. Append a question mark
(?)
to the URL, followed by the query.
Note:
Characters in a URL that are outside the ASCII character set, such as spaces and quotes, must be URL encoded. Examples are provided with URL encoded characters. The + replaces spaces and %22 replaces quotes (").https://tenant-base-url/admin/v1/Users?attributes=email&filter=userName+co+%22jensen%22
To find all AppRoles that are associated with a specific user:
http://tenant-base-url/admin/v1/Users/1e895413c68d42c7bc006d0033794c1e?attributes=groups,urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:appRoles
Query Parameters With a POST /.search Request Body
You can create searches with a POST request on a resource endpoint ending in /.search. In that case, you put the query in the request body. When searching for sensitive information, such as user names, where the sensitive information is submitted along with other data, use this method (for security reasons).
/Users/.search.
It returns the first 10 user entries with
displayName
starting with
smith
and
meta.resourceType
equal to
User.
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"attributes": ["displayName", "userName"],
"filter":
"(displayName sw \"smith\")",
"startIndex": 1,
"count": 10
}
The attributes
parameter can be used with all methods except Delete.
The other query parameters are only meaningful for search methods and are ignored by other methods.
HTTP Query Parameter | Description |
---|---|
attributes=attribute1,attribute2 |
Specifies a multi-valued list of strings indicating the names of resource attributes to return in the response. This query parameter also accepts the extension schema ID as a valid attribute name. Including the extension schema ID in the attributes returns all of the default attributes within it. |
attributeSets |
The search returns a group of attributes in the response rather than specifying each attribute individually. This query parameter accepts comma-separated values from the following parameters:
Note: If bothattributes and
attributeSets are specified in the request, then the values from both are returned in the response.
|
count=N |
Indicates the maximum number of search results per page. Specify a non-negative number to retrieve a response. A negative number defaults to 50 and returns the first 50 resources. |
startIndex=N |
Specifies the start page index. This is the 1-based index of the first query result. A value less than 1 is interpreted as 1. |
filter=Expression |
The search returns all resources in the specified endpoint for which the expression is true. See Using the Filter Query Parameter for more detailed information. |
sortBy=attribute |
Provides the attribute name on which the response should be sorted. |
sortOrder=ascending | sortOrder=descending |
Specifies the order in which the sortBy parameter is applied. If you specify a value for sortBy and do not specify a sortOrder, the sortOrder defaults to ascending. |
Using the Filter Query Parameter
You can use the filter
query in searches that you perform with the GET
method. The format of a filter query is:
filter=Expression
A filter must contain at least one valid expression. Each expression contains an attribute name followed by an attribute operator and optional value. Searchable attributes vary from one resource to another. These are discussed in the topics for those GET
requests.
The following URL includes a filter query for users with the attribute userName
that contains jensen:
Note:
Characters in a URL that are outside the ASCII character set, such as spaces and quotes, must be URL encoded. Examples are provided with URL encoded characters. The + replaces spaces and %22 replaces quotes (").https://tenant-base-url/admin/v1/Users?filter=userName+co+%22jensen%22
Attribute Operator | Description | Behavior |
---|---|---|
eq |
Equal | The attribute and operator values must be identical for a match. |
ne |
Not equal | The attribute and operator values are not identical. |
co |
Contains | The entire operator value must be a substring of the attribute value for a match. |
sw |
Starts with | The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value. This criterion is satisfied if the two strings are identical. |
ew |
Ends with | The entire operator value must be a substring of the attribute value, matching at the end of the attribute value. This criterion is satisfied if the two strings are identical. |
pr |
Present (has value) | If the attribute has a non-empty value, or if it contains a non-empty node for complex attributes, there is a match. |
gt |
Greater than | If the attribute value is greater than operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison and for DateTime types, it is a chronological comparison. |
ge |
Greater than or equal | If the attribute value is greater than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison and for DateTime types, it is a chronological comparison. |
lt |
Less than | If the attribute value is less than operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison and for DateTime types, it is a chronological comparison. |
le |
Less than or equal to | If the attribute value is less than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison and for DateTime types, it is a chronological comparison. |
You can combine multiple expressions by using the logical operators and
and or
and negate an expression by preceding it with the attribute operator not.
Use parentheses ()
for precedence grouping and square brackets []
for complex attribute filter grouping.
Example - URL Filter Examples
Note:
Characters in a URL that are outside the ASCII character set, such as spaces and quotes, must be URL encoded. Examples are provided with URL encoded characters. The + replaces spaces and %22 replaces quotes (").To search for users with the attribute userName
equal to example,
you would use this filter:
https://tenant-base-url/admin/v1/Users?filter=userName+eq+%22example%22
This filter example searches for a User with a userName
that contains jensen:
https://tenant-base-url/admin/v1/Users?filter=userName+co+%22jensen%22
This filter example searches for a user with a userName
that contains either example
or that starts with my:
https://tenant-base-url/admin/v1/Users?filter=userName+co+%22example%22+or+userName+sw+%22my%22
This filter example searches for a User with the familyName
subattribute of name
that contains jensen:
https://tenant-base-url/admin/v1/Users?filter=name.familyName+co+%22jensen%22
This complex URL query example returns all users with a userName
equal to example,
lists the attributes emails.value
and name.familyName
in the JSON response body, and returns a maximum of eight users per page of output.
/Users?filter=userName+eq+%22example%22+&+attributes=emails.value,name.familyName+&+count=8
This filter example searches for all users who have a specific AppRole:
http://tenant-base-url/admin/v1/Users?filter=urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:approles.value+eq+<idOfAppRole>