1. Oracle Identity Cloud Service REST APIREST API for Oracle Identity Cloud Service
  2. Structuring Resource Requests
  3. Query Parameters

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.

Query parameters are typically used with search methods:

Query Parameters With GET

When you perform a search by using a 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).

This example shows the request body of a POST method performed on the endpoint /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:

  • all (returns all attributes)

  • always (returns all attributes marked as always in the schema)

  • default (returns all default attributes)

  • request (returns all attributes marked as request in the schema)

These values are not case-sensitive.

Note:

If both attributes 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>