Manage Collections
A collection resource represents a list of items, such as categories, languages, or locales. You can sort, filter, and paginate your collection resources to make large result sets easier to use and consume. For instance, you might only want to select a subset of information from a content collection resource, instead of the entire data set. You can manage data returned from a collection resource using the following actions:
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 REST 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.
Note:
You must sort the results using only unique attributes, such asOptyId or
PartyNumber, to get predictable results. For example, to get to the first page of opportunities, use the command:
GET /opportunities?orderBy=OptyIdAssuming that in the response, the last opportunity returned has OptyId = 1000, then to get to the next page, the GET request should be structures as:
GET /opportunities?orderBy=OptyId>100The example URI to get schema and catalog information of the resource is as follows:
https://<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.
Example Requests
The example request to sort a list according to case sensitivity are as follows:
GET /content?orderBy=title:case-sensitiveThe request returns Content objects that are sorted by their title case sensitively.
{ "items": [ { "contentType": { "recordId": "33B9C302D8264371B6A12EDAF3FD974B", "referenceKey": "FAQ", "name": "FAQ", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/33B9C302D8264371B6A12EDAF3FD974B", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-09-27T12:23:49-0600", "dateAdded": "2016-09-27T12:23:49-0600", "displayStartDate": "2016-09-27T12:23:22-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-09-27T12:23:49-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "040036719791200157210710b5007f7a", "versionId": "040036719791200157210710b5007f7b", "documentId": "FAQ1", "title": "test - content", "version": "1.0", "answerId": 1000000, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-20T12:37:09-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/040036719791200157210710b5007f7a", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, { "contentType": { "recordId": "33B9C302D8264371B6A12EDAF3FD974B", "referenceKey": "FAQ", "name": "FAQ", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/33B9C302D8264371B6A12EDAF3FD974B", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-10-18T03:23:28-0600", "dateAdded": "2016-10-18T03:23:30-0600", "displayStartDate": "2016-10-18T03:22:00-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-10-18T03:23:30-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "040087068a90cb00157d5295740007fdf", "versionId": "040087068a90cb00157d5295740007fde", "documentId": "FAQ10", "title": "How To Maintain Summary Templates", "version": "1.0", "answerId": 1000018, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-18T03:23:30-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/040087068a90cb00157d5295740007fdf", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, { , ], "hasMore": true, "limit": 20, "offset": 0, "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content?limit=20&offset=0&orderBy=documentId:case-sensitive", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "next", "href": "https://<IM_REST_API_HOST>/km/api/latest/content?limit=20&offset=20&orderBy=documentId:case-sensitive", "mediaType": "application/json, application/xml", "method": "GET" } ], "count": 2 }GET /content?orderBy=title:case-insensitiveThe request returns Content objects that are sorted by their documentId parameter value case-insensitively.
{ "items": [ { "contentType": { "recordId": "33B9C302D8264371B6A12EDAF3FD974B", "referenceKey": "FAQ", "name": "FAQ", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/33B9C302D8264371B6A12EDAF3FD974B", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-10-18T04:01:19-0600", "dateAdded": "2016-10-18T04:01:19-0600", "displayStartDate": "2016-10-18T04:00:00-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-10-18T04:01:19-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "040087068a90cb00157d5295740007f9a", "versionId": "040087068a90cb00157d5295740007f99", "documentId": "FAQ22", "title": ">How To Compile Invalid Packages", "version": "1.0", "answerId": 1000030, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-18T04:01:19-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/040087068a90cb00157d5295740007f9a", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, { "contentType": { "recordId": "BC015169991F49738196682D57E7C5E3", "referenceKey": "SOLUTION", "name": "Solution", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/BC015169991F49738196682D57E7C5E3", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-10-19T08:30:49-0600", "dateAdded": "2016-10-19T08:30:49-0600", "displayStartDate": "2016-10-19T08:28:39-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-10-19T08:30:49-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "04008665a7af600157d88f87fa007edc", "versionId": "04008665a7af600157d88f87fa007ed8", "documentId": "SOL79", "title": "1099 Forms Prints Only 33 Characters For Supplier Name", "version": "1.0", "answerId": 1000162, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-19T08:30:49-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/04008665a7af600157d88f87fa007edc", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, { "contentType": { "recordId": "BC015169991F49738196682D57E7C5E3", "referenceKey": "SOLUTION", "name": "Solution", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/BC015169991F49738196682D57E7C5E3", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-10-19T08:27:52-0600", "dateAdded": "2016-10-19T08:27:52-0600", "displayStartDate": "2016-10-19T08:26:43-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-10-19T08:27:52-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "04008665a7af600157d88f87fa007ee2", "versionId": "04008665a7af600157d88f87fa007ee1", "documentId": "SOL78", "title": "11i - Autoinvoice Fails Validation On A Credit Memo From Project Accounting", "version": "1.0", "answerId": 1000161, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-19T08:27:52-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/04008665a7af600157d88f87fa007ee2", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, ], "hasMore": true, "limit": 20, "offset": 0, "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content?limit=20&offset=0&orderBy=title:case-insensitive", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "next", "href": "https://<IM_REST_API_HOST>/km/api/latest/content?limit=20&offset=20&orderBy=title:case-insensitive", "mediaType": "application/json, application/xml", "method": "GET" } ], "count": 3 }
Sorting Syntax
When you request sorting by order values and case sensitivity always specify the order values before the case sensitivity. You can sort the collection of resources by providing multiple fields with the orderBy parameter. When multiple fields are specified, resource collections is sorted according to the order the fields are specified.
Example Requests
The example request to sort a list with multiple fields are as follows:
GET /content?orderBy=title:desc:case-insensitiveThe request returns Content objects that are sorted by their title in descending order. The titles are sorted case-insensitively.
GET /content?orderBy=title:case-sensitive,dateAdded:descThe request returns Content objects that are sorted by their title with case sensitivity in ascending order. A second level sorting is done by their dateAdded parameter value in descending order.
Querying
The Knowledge in B2B Service 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.
Example Requests
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.
Example Requests (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 documentId in ascending order.