Manage Collections

Paginating

Pagination is the placement of a limit on the number of records returned by an operation, often for performance reasons. If a collection is large, then it might be difficult for a client to handle the size of the request. As a result, you can divide many collections into pages.

In REST APIs, paging applies to collection resources only. Each request returns only a chunk of the member resources instead of returning all the member resources. Also, the client may require only a subset of the items in a collection and should be able to request that subset in one or more pages.

The pagination query parameters are as follows:

limit: Indicates the number of records to return in the response. The default value is 10, and the maximum value is 100. The parameter type is unsigned integer.
For example, GET /rest/ofscCore/v1/activities/4225270/customerInventories?limit=3 returns the first 3 activity inventory records.
offset: Determines the record number from which to start retrieval. The default value is zero. The parameter type is unsigned integer.
For example, GET /rest/ofscCore/v1/activities/4225270/customerInventories?limit=3&offset=4 returns the fourth, fifth, and sixth records from the activity inventories.

The pagination response parameters are as follows:

limit: The limit value specified in the request.
offset: The offset value specified in the request.
totalResults: The total number of records in the collection.

The pagination links are as follows:

prev: The link to the previous page of the collection. The response returns this link only if the page is available, that is, offset > 0.
next: The link to the next page of the collection. The response returns this link only if the page is available, that is, offset + limit < totalResults.

A pagination example is as follows:

The following example with the request parameters limit=3 and offset=4 returns the fourth, fifth, and sixth records from the activity inventories.

Example Request


GET /rest/ofscCore/v1/activities/4225270/customerInventories?limit=3&offset=4 HTTP/1.0
Authorization: Basic c29hcEBmb2ZzY2NvcmVhcGk6MQ==
Host: 10.175.251.51
Accept: */*

Example Response


HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Mon, 29 Feb 2016 13:23:55 GMT
Content-Type: application/json; charset=utf-8
Connection: close
X-Powered-By: PHP/5.5.31
{
    "totalResults": 9,
    "limit": "3",
    "offset": "4",
    "items": [
        {
            "inventoryId": 21258550,
            "status": "customer",
            "inventoryType": "NORMAL",
            "serialNumber": "TEST_INVSN_5",
            "quantity": 1,
            "activityId": 4225270
        },
        {
            "inventoryId": 21258551,
            "status": "customer",
            "inventoryType": "NORMAL",
            "serialNumber": "TEST_INVSN_6",
            "quantity": 1,
            "activityId": 4225270
        },
        {
            "inventoryId": 21258552,
            "status": "customer",
            "inventoryType": "NORMAL",
            "serialNumber": "TEST_INVSN_7",
            "quantity": 1,
            "activityId": 4225270
        }
    ],
    "links": [
        {
            "rel": "canonical",
            "href": "http://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4225270/customerInventories"
        },
        {
            "rel": "describedby",
            "href": "http://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/metadata-catalog/activities"
        },
        {
            "rel": "prev",
            "href": "http://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4225270/customerInventories?limit=3&offset=1"
        },
        {
            "rel": "next",
            "href": "http://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities/4225270/customerInventories?limit=3&offset=7"
        }
    ]
}

Filtering

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. For example, the following request returns a record that has activityId as 12345, includeAvatarImageData as true, and resourceFields as STAR_RATING.

https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/whereIsMyTech?activityId=12345&includeAvatarImageData=true&resourceFields=STAR_RATING

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.

Querying

For some collections, you can specify a complex query statement, which can include one or more fields or custom properties using q query parameter in the request URL. For example, the following request returns only those records that have status as pending and slaWindowEnd earlier than '2016-10-23'.

https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/activities?q=status=='pending'and slaWindowEnd<'2016-10-23'

Note:

Not all collections support querying. Please refer to the individual endpoint parameters in the Tasks section for more information.