Collections
A collection represents the list of records that are returned by Oracle IoT Cloud Service as a result of a user request for several resources, such as endpoints and endpoints/configurations.
Representation
{
"items": [
<single resource json>,
...
<single resource json>
],
"count":6,
"limit":10,
"offset":0,
"hasMore": false,
"links": [
{
"rel":"canonical",
"href":http://.../iot/api/v1/endpoints
},
{
"rel":"self",
"href":http://.../iot/api/v1/endpoints?offset=0&limit=10
},
{
"rel":"first",
"href":http://.../iot/api/v1/endpoints?offset=0&limit=10
},
{
"rel":"last",
"href":http://.../iot/api/v1/endpoints?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 betrue
orfalse
to indicate whether the collection has at least another page of response. -
links
provides any paging navigation links, if applicable. The possible values arefirst
,next
,prev
, andlast
links.
Paging
-
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.
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 /endpoints
resource will include a list of endpoint 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 endpoint 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 endpoints/{id}/metadata
. This option is not used for root collections, such as /endpoints
. Only patching a single resource using id
is used
Ordering
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
ordesc
indicates the records should be sorted in an ascending or descending order. If neither are indicated, theasc
sort order is used by default.
/endpoints?orderBy=created:desc,state
indicates that the
endpoints
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 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.