Manage Collections
This section describes the actions you can perform on a collection of REST resources.
Filtering
Filtering is required to limit the amount of data that is returned and displayed in the REST client.
The following table describes some of the filter operations that you can perform on the resources with example URIs.
| Operation | Method | Example URI | Description |
|---|---|---|---|
| Retrieving all the content |
GET |
|
Returns a paginated list of Content objects in the extended mode. |
| Retrieving a content object by its record ID |
GET |
|
Returns a Content object in the FULL mode displaying the published version of the content in the default locale. |
Paginating
To paginate a collection of resources, you can use parameters such as limit and offset. Most of the resources that return a collection of resources support these parameters.
The following table explains the limit and offset parameters which are used for pagination.
| Parameter | Description |
|---|---|
| limit | A positive integer value that specifies the maximum number of items returned by the server. The server may override the value for performance reasons. If no limit value is specified by the client, then the server uses a default limit value. |
| offset | A non-negative integer value that specifies the index of the first item to be returned. The offset index begins at 0. If no offset value is specified by the client, then the server uses a default value of 0. |
A simple paging can be achieved by specifying both the limit and offset query parameters.
For example, when a GET request is submitted using content ?offset=10&limit=20, the response contains at the most 20 content objects ranging from the 11th to 30th position of all content objects.
Note:
While using the limit and offset parameters you may encounter inconsistencies if items in the resource collection are updated in between paging requests.Sorting
The orderBy request parameter is used to sort the list of objects that you receive when you request a collection of objects. Most of the methods support orderBy request parameter.
You can find the different values to use with the orderBy parameter in the schema and catalog information of the resource. To get the schema and catalog information, use GET method with the mediaType value as "application/schema+json" in the HTTP request.
The example URI to get schema and catalog information of the resource is as follows:
http://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/{resourceName}
In the response to this request you must look for the schema properties that have the sortable flag set as true; these are the only fields of the resource that can be used with the orderBy request parameter.
Most resources support the schema catalog request. When a resource does not support the schema catalog request, see the specific documentation to get the additional values to use with orderBy parameter.
Sort Order
You can sort the resource collections in either ascending or descending order by specifying asc or desc as a part of the orderBy parameter value. If no order is specified, then by default the orderBy parameter sorts the resource collection in ascending order.
Example Request
The example request to sort a list in ascending or descending are as follows:
GET /content?orderBy=documentIdThe request returns Content objects that are sorted by their documentId parameter value in ascending order.
GET /content?orderBy=documentId:descThe request returns Content objects that are sorted by their documentId parameter value in descending order.
Case Sensitivity
You can sort the resource collections by case sensitivity by specifying case-sensitive or case-insensitive as a part of the orderBy parameter value. If no case sensitivity is specified, then by default parameter sorts the list according to the standard case sensitively of the field used with the orderBy parameter.
Querying
The Oracle B2C Service Knowledge Advanced REST APIs provide query support to filter a set resource collection. You can achieve querying by using the q request parameter with the request. The value of the q request parameter contains one or more expressions involving the resource's query parameters to execute a "where" clause in the request. Query requests also support paginating and sorting of the items returned in the resource collection. The "where" clause or value of the q request parameter is referred to as a query. Most of the resources support q request parameters. For more information, see Supported Query Parameters.
Note:
The value of the q request parameter must be in a single line. To avoid white spaces, the q request itself has to be URL Encoded.Example Requests (with URL Encoding)
The following are examples of the query requests with the URLs encoded.
GET /content?q=dateAdded+after+'2015-01-01'&orderBy=dateAdded:desc&limit=10&offset=11The request returns at most 10 Content objects created after January 1, 2015, sorted by most recently added, starting with the eleventh Content matching the query.
GET /content?q=title+likeAny+('*Oracle+Knowledge*')+and+dateAdded+after+'2015-01-01'&orderBy=documentIdThe request returns Content objects with a title including the term "Oracle Knowledge" that were created after January 1, 2015, sorted by their documentId in ascending order.
Example Requests (without URL Encoding)
The following are examples of the q requests. In this example queries are not URL encoded.
GET /content?q=dateAdded after '2015-01-01'&orderBy=dateAdded:desc&limit=10&offset=11The request returns at most 10 Content objects created after January 1, 2015, sorted by most recently added, starting with the eleventh Content matching the query.
GET /content?q=title likeAny ('*Oracle Knowledge*') and dateAdded after '2015-01-01'&orderBy=documentIdThe request returns Content objects with a title including the term 'oracle Knowledge' that were created after January 1, 2015, sorted by their documented parameter value in ascending order.