Manage Collections

You can use Oracle B2C Service REST API to retrieve a single record or a collection of records for a REST resource. The following table lists the various operations that you can perform on a collection:

Operation	Description
Filtering	You can specify the data to be returned and displayed in the response. For some collections, you can use filter expressions to specify one or more conditions in the request URL. The record or records matching the conditions are returned in the response. Note: The filtering parameters depend on the operation, and not all collections support filtering. Please refer to the individual endpoint parameters in the Tasks section for more information.
Paginating	You can limit the number of records that are displayed on a page in the response.
Sorting	You can sort the records returned in a response using the `orderBy` query parameter.
Querying	You can use RightNow Object Query Language (ROQL) queries to perform searches on the REST API. For more information on ROQL queries, see: Run ROQL Object Queries Run ROQL Tabular Queries Query ROQL Managed Tables You can use query parameters to specify various conditions for retrieving resource records. For more information, see Supported Query Parameters.

Paginating

Pagination is the placement of a limit on the number of records returned by an operation, often for performance reasons. The limit is called the page size. In the Connect REST API, the default page size is 1000 records.

In the November 2015 release and later, you can change the number of records displayed and the record with which to start displaying results. You use the following query parameters for pagination:

Using Query Parameters for Pagination

You use the following query parameters for pagination:

limit. Sets the page size.
offset. Determines the record number from which to start retrieval.
totalResults. Displays the total number of results.

Note:

Only collection resources, such as incidents and contacts, support pagination. The maximum page size is 20,000 records.

When you set a page size, the collection response includes the following:

hasMore. Tells you whether there are any more records to display.
prev and next links. Enables you to navigate to the previous or next set of results if they exist.

Note:

Oracle recommends using the prev and next links, rather than the offset parameter, to navigate. The offset parameter affects performance significantly.

Using Pagination with Collection Resources

You use the GET method with the following syntax to use pagination with collection resources:

https://your_site_interface/services/rest/connect/version/
resource?limit=number_of_records[&totalResults=true]

For example, the following GET request:

https://mysite.example.com/services/rest/connect/v1.4/accounts?limit=20&totalResults=true

returns the first 20 accounts. The total number of accounts, the fact that there are more accounts that can be retrieved, and a next link (but not prev) are also shown:

{
    "items": [
        {
            "id": 1,
            "lookupName": "Administrator",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/1"
                }
            ]
        },
        {
            "id": 2,
            "lookupName": "Susan Meadows",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/2"
                }
            ]
        },

    ...
        {
            "id": 26,
            "lookupName": "Holly Chatagent",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/26"
                }
            ]
        }
    ],
    "totalResults": 28,
    "hasMore": true,
    "links": [
        {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
        },
        {
            "rel": "describedby",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
            "mediaType": "application/schema+json"
        },
        {
            "rel": "next",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts?totalResults=true&limit=20&fromID=26"
        },
        {
            "rel": "search-form",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts-search-form"
        },
        {
            "rel": "self",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts?limit=20&totalResults=true"
        }
    ]
}

Combining Pagination with Other Query Parameters

You can combine pagination with other query parameters, such as q and fields, to refine your results. For example, these GET method requests are valid:

https://mysite.example.com/services/rest/connect/v1.4/accounts
?fields=displayName,login&limit=20&totalResults=true

https://mysite.example.com/services/rest/connect/v1.4/accounts
?q=passwordExpirationTime>'2019-01-30T15:59:00Z'&limit=20&totalResults=true

Using Pagination with ROQL Tabular Queries

You can use pagination with ROQL tabular queries to refine your results, by using the limit parameter as part of the query. For more information, see Run ROQL Tabular Queries.

Use the following GET request to return the first 50 rows from the accounts table:

https://mysite.example.com/services/rest/connect/v1.4/
queryResults?query=select * from accounts limit 50

Use this GET request to get the next 50 accounts:

https://mysite.example.com/services/rest/connect/v1.4/
queryResults?query=select * from accounts  where ID>50 limit 50

Repeat the process by incrementing the where ID> integer expression by 50 (100, 150, and so on).

Sorting

You use the orderBy query parameter to sort data.

By default, data returned by the REST API is sorted by ID number in ascending order. In the November 2015 release and later, sorting allows REST clients to display returned data in a chosen order.

Note:

Only collection resources, such as accounts, incidents, and contacts, support sorting.

You use the GET method with the following syntax to sort data returned from collection resources:

https://your_site_interface/services/rest/connect/version/resource
?orderBy=comma-separated columns[:asc|desc]

Example: Sorting by LookupName

You can sort incidents by reference number (that is, LookupName) in descending order. Use a GET request with the following syntax:

https://mysite.example.com/services/rest/connect/v1.4/accounts?orderBy=lookupName:desc

The following data is returned:

{
    "items": [
        {
            "id": 3,
            "lookupName": "Lucy Bauer",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/3"
                }
            ]
        },
        {
            "id": 11,
            "lookupName": "John Jergenson",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/11"
                }
            ]
        },
        {
            "id": 26,
            "lookupName": "Holly Chatagent",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/26"
                }
            ]
        },

...        {
            "id": 17,
            "lookupName": "Abby Parker",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/17"
                }
            ]
        }
    ],
    "hasMore": false,
    "links": [
        {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
        },
        {
            "rel": "describedby",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
            "mediaType": "application/schema+json"
        },
        {
            "rel": "search-form",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts-search-form"
        },
        {
            "rel": "self",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts?orderBy=lookupName:desc"
        }
    ]
}

Note:

In this example, you can also perform the same sort by using the id field in descending order.

Example: Sorting Combined with Fields Query

You can combine sorting with other query parameters, such as the fields parameter used for filtering results by field.

The following GET request:

https://mysite.example.com/services/rest/connect/v1.4/accounts?fields=displayName,login&orderBy=displayName

returns the following:

{
    "items": [
        {
            "id": 17,
            "lookupName": "Abby Parker",
            "displayName": "Abby Parker",
            "login": "aparker",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/17"
                }
            ]
        },
        {
            "id": 21,
            "lookupName": "Chucky Chatagent",
            "displayName": "Chucky Chatagent",
            "login": "chuckychat",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/21"
                }
            ]
        },

...
        {
            "id": 12,
            "lookupName": "Matthew Gold",
            "displayName": "Mathew Gold",
            "login": "mgold",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/12"
                }
            ]
        },
    ],
    "hasMore": false,
    "links": [
        {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
        },
        {
            "rel": "describedby",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
            "mediaType": "application/schema+json"
        },
        {
            "rel": "search-form",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts-search-form"
        },
        {
            "rel": "self",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts?fields=displayName,login&orderBy=displayName"
        }
    ]
}

Example: Sorting Combined with Other Query Parameters

This is another example of combining sorting with various query parameters.

The following GET request:

https://mysite.example.com/services/rest/connect/v1.4/accounts?
q=manager IS NULL&totalResults=true&orderBy=displayName

returns:

{
    "items": [
        {
            "id": 17,
            "lookupName": "Abby Parker",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/17"
                }
            ]
        },

        {
            "id": 19,
            "lookupName": "Amy Chatagent",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/19"
                }
            ]
        },

    ...
        {
            "id": 3,
            "lookupName": "Lucy Bauer",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/3"
                }
            ]
        },
    ],
    "totalResults": 13,
    "hasMore": false,
    "links": [
        {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
        },
        {
            "rel": "describedby",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
            "mediaType": "application/schema+json"
        },
        {
            "rel": "search-form",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts-search-form"
        },
        {
            "rel": "self",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts?q=manager%20IS%20NULL&totalREsults=true&orderBy=displayName"
        }
    ]
}