Collections

A collection represents the list of records that are returned by Oracle IoT Fleet Monitoring Cloud Service as a result of a user request for several resources, such as trips and vehicles.

Representation

A collection of resources is represented as a JSON array, similar to the following:

{
    "items": [ 
        <single resource json>,
        ...
        <single resource json>
    ],
    "count":6,
    "limit":10,
    "offset":0,
    "hasMore": false,
    "links": [
        {
             "rel":"canonical",
             "href":http://.../fleetMonitoring/clientapi/v2/trips
        },
        {
             "rel":"self",
             "href":http://.../fleetMonitoring/clientapi/v2/trips?offset=0&limit=10
        },
        {
             "rel":"first",
             "href":http://.../fleetMonitoring/clientapi/v2/trips?offset=0&limit=10
        },
        {
             "rel":"last",
             "href":http://.../fleetMonitoring/clientapi/v2/trips?offset=0&limit=10
        }
    ]
}

where

• count is the number of records in response

• limit gives the current maximum number of records returned

• offset is the number that the first record of results is starting from

• hasMore can either be true or false to indicate whether the collection has at least another page of response.

• links provides any paging navigation links, if applicable. The possible values are first, next, prev, and last links.

Paging

You can use paging to minimize the number of records returned in a result collection. Paging allows you to do the following:

• use an offset query parameter value, like 3, to point to the first record in the result collection.

• use a limit query parameter value, like 10, to limit the number of records returned per page.

The sample values in the pair of query parameters above means that the first record in the result collection would have 3 as the order number and the page of response would have a total of 10 records in it.

When the query parameter and value of totalResults=true are used, the total number of records in result collection should be exists. The field hasMore would be set to true if the result collection has more than the offset+limit records and set to false on the last page of response.

If a value is not specified for the limit query parameter, the default value is set to 10. The maximum limit value for is 200. A limit value greater than 200 will result in an error, as will a limit less than or equal to 0. The default value for the offset query parameter is 0. An offset value less than 0 results in an error. An offset value greater than the total number of results will yield an empty result list.

Expansion

The expand option is used to get the details on the resources instead of just links to the records. If a results collection includes a resource that has a sub-resource that is also a collection, the expand option can be used to get the detailed info for that sub-resource. .

For example, the expand=metadata on /trips resource will include a list of trip metadata in the response. By default, such sub-resources contains only links to decrease the amount of data included in a response. Note that the use of the expand option is necessary when registering devices, as the trip ID that the device is registered under is only visible when the expand option is used

Patching

The patch option allows a single resource in a collection to be updated. It is only used in specific cases, such as changing trips/{id}/metadata. This option is not used for root collections, such as /trips. Only patching a single resource using id is used

Ordering

The orderBy query parameter is used to order the records included in a response collection. It has following syntax:

orderBy=fieldname1:[asc|des],...fieldNameN:[asc|desc]

where

• orderBy is the reserved word

• fieldName1,...,fieldNameN are the names of the fields in the resource record

• asc or desc indicates the records should be sorted in an ascending or descending order. If neither are indicated, the asc sort order is used by default.

.

For example,

/trips?orderBy=created:desc,state

indicates that the trips records should be sorted using the created field in a descending date order and by the state field by ascending state order.

Note:

The date representation in the Oracle IoT Fleet Monitoring Cloud Service user interface does not show milliseconds. This can cause items (with different times on the same date) to appear to be sorted incorrectly when a request performs ordering by a combination of date and some other criteria.