Return a List of Objects
/mobile/platform/storage/collections/{collection}/objects
This operation returns a list of the objects within the collection.
If the collection is isolated and you have READ_ALL
or READ_WRITE_ALL
access, then you must include the user
query parameter and specify which user's objects you want listed, even if you want to see your own objects (use *
to list all users' objects). Note that you provide the user's ID, not the user name. If the collection is isolated and you have READ
access, then your objects are listed automatically. You don't need to include the user
query parameter.
Example
The following example retrieves the list of objects that are stored in the collection myCollection
.
curl -X GET -H "Authorization ..." {HOST}/mobile/platform/storage/collections/myCollection/objects
Permissions
- Anonymous Access: If the following are true, then you can access this operation anonymously or as any user, regardless of assigned roles.
- The backend allows anonymous access.
- The
Security_CollectionsAnonymousAccess
environment policy lists the collection. - The collection is shared
- Role-Based Access:
- You must have been granted one of the following permissions to the collection:
READ
READ_ALL
READ_WRITE
READ_WRITE_ALL
- For role-based backends, you must have a role that enables access to the backend.
- You must have been granted one of the following permissions to the collection:
Request
-
collection: string
The name of the collection that you want to access.
When you look at the metadata for the collection, this parameter corresponds to the
id
value:{ "id": "pictures", "description": "Application images", "contentLength": 6205619, "eTag": "\"1.0\"", "links": [ { "rel": "canonical", "href": "/mobile/platform/storage/collections/images" }, { "rel": "self", "href": "/mobile/platform/storage/collections/images" } ] }
-
limit(optional): number
The maximum number of items to return. If a limit is not specified, or if the requested limit is greater than 100, then 100 is used instead. The response contains the actual limit used, and also a link to get the next set of items (if the total number of items is greater than the limit).
Example - ?limit=10
The following example shows a response to a request that specified a limit of 10 items:
{ "items" : [ ... ], ... "limit": 10, ... "links" : [ ..., { "rel" : "next", "href" : "...?limit=10&offset=10" } ] }
-
offset(optional): number
Specify the index where you want to start browsing the list of items. If you don't specify an offset, then the offset defaults to
0
, which is the first item in the list. The response contains the offset used, and also a link to get the previous set of items.Example - ?offset=200
The following example shows a response to a request that specified an offset of
200
items.{ "items" : [ ... ], ... "offset": 200, ... "links" : [ ..., { "rel" : "prev", "href" : "...?limit=100&offset=100" }, ... ] }
-
orderBy(optional): string
Use this query parameter to sort the results by
name
,modifiedBy
,modifiedOn
,createdBy
,createdOn
, andcontentLength
.Example #1 - Order By name Ascending (asc)
In the following example, the items are sorted in alphabetical order by name.
?orderBy=name:asc
Example #2 - Order By modifiedOn Descending (desc)
In the following example, the items are sorted by the date on which they were last modified. The most recently modified file will appear first.
?orderBy=modifiedOn:desc
-
q(optional): string
The items that are returned are based on a case-insensitive partial match of the
id
,name
,createdBy
ormodifiedBy
properties of an item.Example - ?q=sam
The following example shows a result based on a query for
sam
.{
}"items" : [ { "id" : "anx12sam3" ... }, { ... "name" : "Sesame Seeds" ... }, { ... "createdBy" : "SAMANTHA" ... }, { ... "modifiedBy" : "sam" ... } ... ], ... "links" : [ ... ]
-
totalResults(optional): boolean
When this query parameter is present with a value of
true
, then the HTTP response contains thetotalResults
attribute with a value that represents the total number of items in the collection. By default, the response does not contain this value.Example - ?totalResults=true
{ "items" : [ ... ], ... "totalResults" : 123, ... "links" : [ ... ] }
-
user(optional): string
This is the ID (not the user name) of a user. Use
*
(wildcard) to get all users. This query parameter allows a user withREAD_ALL/READ_WRITE_ALL
permission to access another user's isolated space. A user withREAD/READ_WRITE
permission may access only their own space.
-
Accept(optional): string
The media types that the client prefers for the response body. If the service doesn't support any of these types, then it returns a
406
status code, and the response body lists the media types that it supports.Examples
*/*
application/*
application/json
application/xml,application/json
-
Oracle-Mobile-Sync-Agent(optional): boolean
When this header is present in the request, and has a value of
true
, then the response contains the information required by the Sync Client SDK to cache the data locally for offline use.
Response
- application/json
200 Response
OK
The operation completed successfully.
-
Cache-Control: string
This header describes how the result may be cached:
Collection Without Isolation
Collections without any specified isolation return the following HTTP response header. The
no-cache
portion ensures that authorization is respected.Cache-Control: public, no-cache
Collection With Isolation
Collections with a specified isolation return the following HTTP response header. The
private
portion indicates that the result is specific to the user making the request.Cache-Control: private, no-cache
-
Oracle-Mobile-Sync-Resource-Type: string
The Sync Client SDK uses this header.
Allowed Values:[ "collection" ]
object
Object Array
-
count:
integer
Minimum Value:
0
The number of items returned. -
etags:
array etags
Minimum Number of Items:
0
Maximum Number of Items:100
The ETags that correspond to the returned items. This value is returned only when the request includes the `Oracle-Mobile-Sync-Agent` HTTP request header with a value of `true`. -
hasMore:
boolean
Flag indicating if there are more items to be returned. The value is `true` if there are more items. When `true`, you can use the `next` link to retrieve the next set of items.
-
items:
array items
Minimum Number of Items:
0
Maximum Number of Items:100
Metadata for an object in the collection. -
limit:
integer
Minimum Value:
0
Maximum Value:100
The maximum number of items returned. This value (an integer up to `100`) is specified using the `limit` query parameter. -
links:
array links
Minimum Number of Items:
0
The links that you can use to explore the resource. -
offset:
integer
Minimum Value:
0
The index of the first item returned. This is either the value that was specified with the `offset` query parameter or `0` to indicate the first item. -
totalResults:
integer
Minimum Value:
0
The total number of items. This value is returned only when the request includes the query parameter `totalResults` with a value of `true`. -
uris:
array uris
Minimum Number of Items:
0
Maximum Number of Items:100
The canonical links that correspond to the returned items. This value is returned only when the request includes the `Oracle-Mobile-Sync-Agent` HTTP request header with a value of `true`.
array
0
100
-
[0]:
object Object
Title:
Object
array
0
-
[0]:
object Link
Title:
Link
array
0
100
object
Object
-
contentLength:
integer
The size of object in bytes.
-
contentType:
string
Maximum Length:
255
The media type of the object. For example, a JPEG image would have a media type of image/jpeg. -
createdBy:
string
The user name for the user who created the object.
-
createdOn:
string
The date and time, in ISO 8601 format, that the object was created (for example, 2014-06-30T01:02:03Z).
-
eTag:
string
An identifier that was assigned to this version of the object. This value changes whenever the object is updated. The value includes the starting and ending quotation marks (for example, "2"). You can use an ETag value with the `IF-MATCH` and `IF-NONE-MATCH` HTTP request headers.
-
id:
string
Minimum Length:
1
Maximum Length:1024
The object's unique identifier. This is the value that is used in the URI to access the object. -
links:
array links
Minimum Number of Items:
0
The links that you can use to explore the resource. -
modifiedBy:
string
The user name for the user who last modified the object.
-
modifiedOn:
string
The date and time, in ISO 8601 format, that the object was last modified (for example, 2014-06-30T01:02:03Z).
-
name:
string
Maximum Length:
1024
The display name for the object. -
user:
string
For user-isolated collections, the ID of the user that the object belongs to.
array
0
-
[0]:
object Link
Title:
Link
object
Link
-
href:
string
A relative URL.
-
rel:
Allowed Values:
[ "self", "canonical", "prev", "next" ]
The type of link.
{
"totalResults":7,
"offset":4,
"hasMore":true,
"limit":2,
"count":2,
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/pictures/objects/"
},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/pictures/objects?offset=4&limit=2&orderBy=name:asc&totalResults=true"
},
{
"rel":"prev",
"href":"/mobile/platform/storage/collections/pictures/objects?offset=2&limit=2&orderBy=name:asc&totalResults=true"
},
{
"rel":"next",
"href":"/mobile/platform/storage/collections/pictures/objects?offset=6&limit=2&orderBy=name:asc&totalResults=true"
}
],
"items":[
{
"modifiedOn":"2014-11-20T15:58:09Z",
"createdBy":"jdoe",
"name":"Profile Picture",
"eTag":"\"2\"",
"modifiedBy":"jdoe",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/pictures/objects/profile-pic"
},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/pictures/objects/profile-pic"
}
],
"contentLength":937647,
"id":"profile-pic",
"createdOn":"2014-11-20T15:57:04Z",
"contentType":"image/png"
},
{
"modifiedOn":"2014-11-20T18:27:02Z",
"createdBy":"jsmith",
"name":"Background",
"eTag":"\"1\"",
"modifiedBy":"jsmith",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/pictures/objects/0683d48b-fdc5-4397-8ca2-824e2b0cae65"
},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/pictures/objects/0683d48b-fdc5-4397-8ca2-824e2b0cae65"
}
],
"contentLength":5266432,
"id":"0683d48b-fdc5-4397-8ca2-824e2b0cae65",
"createdOn":"2014-11-20T18:27:02Z",
"contentType":"image/jpeg"
}
]
}
400 Response
Bad Request
This status is returned if you attempt to:
- Make a call without specifying the
Oracle-Mobile-Backend-ID
HTTP request header. - Specify the
user
query parameter for an endpoint that isn't an object level operation for an isolated collection. - Specify an incorrect value for a query parameter.
- Store an object with an identifier longer than the maximum allowed size.
- Store an object where the actual size of the object is different from what was specified in the
Content-Length
HTTP request header.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
The service's error code.
-
o:errorDetails:
array o:errorDetails
Minimum Number of Items:
0
Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
[0]:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
401 Response
Unauthorized
The user is not authenticated. The request must be made with the Authorization
HTTP request header.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
The service's error code.
-
o:errorDetails:
array o:errorDetails
Minimum Number of Items:
0
Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
[0]:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
403 Response
Forbidden
This status is returned if you attempt to:
- Make a request with a user who doesn't have a role that's associated with the backend.
- Retrieve an object without being assigned a role that has
READ
orREAD_WRITE
access for a non-anonymous collection. - Retrieve an object from your isolated space without being assigned a role that has
READ
,READ_WRITE
,READ_ALL
, orREAD_WRITE_ALL
access for the collection. - Retrieve an object from another user's isolated space without being assigned a role that has
READ_ALL
orREAD_WRITE_ALL
access for the collection. - Store an object without being assigned a role that has been granted
READ_WRITE
access for a non-anonymous collection. - Store an object to your isolated space without being assigned a role that has
READ_WRITE
orREAD_WRITE_ALL
access for the collection. - Store an object to another user's isolated space without being assigned a role that has
READ_WRITE_ALL
access for the collection.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
The service's error code.
-
o:errorDetails:
array o:errorDetails
Minimum Number of Items:
0
Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
[0]:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
404 Response
Not Found
A collection with the given identifier does not exist.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
The service's error code.
-
o:errorDetails:
array o:errorDetails
Minimum Number of Items:
0
Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
[0]:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
406 Response
Not Acceptable
The media type of the resource isn't compatible with the values in the Accept
header.
For example, you see this error when you try to request a resource that has the media type application/json
and the Accept
header value is application/xml
.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
The service's error code.
-
o:errorDetails:
array o:errorDetails
Minimum Number of Items:
0
Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
[0]:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
Examples
Example of Retrieving a List of Objects in a Shared Collection
This example shows how to use cURL to retrieve a list of objects in a shared collection by submitting a GET request on the REST resource. This example inquires about the objects in the technicianNotes
collection.
curl -i \
-X GET \
-u mobile.user@example.com:password \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects
Example of Retrieving a List of Objects in an Isolated Collection
This example shows how to use cURL to retrieve a list of objects that are stored in an isolated collection by submitting a GET request on the REST resource. Because the collection is isolated, the request must include the user
query parameter.
curl -i \
-X GET \
-u mobile.user@example.com:password \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects?user=8c8f1a5a-e56b-494b-9a99-f03d562c1ee7
Example of Paging Through a List of Objects
If you don't want to see all the results, or if you want to get the results in small blocks, use the limit
and offset
query parameters to request a subset of response items. This example uses limit
to restrict the number of items returned to 10
and offset
to specify that the response should start with the eleventh item. Note that the offset
value is zero based. That is, you use 0
for item 1
.
curl -i \
-X GET \
-u mobile.user@example.com:password \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects?offset=10&limit=10
Example of Ordering the List of Objects
You can use the orderBy
query parameter to sort the results by name
, modifiedBy
, modifiedOn
, createdBy
, createdOn
, or contentLength
, as shown in this example. You also can specify whether to sort in ascending (asc
) or descending (desc
) order.
curl -i \
-X GET \
-u mobile.user@example.com:password \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects?orderBy=contentLength:desc
Example of Searching for Objects
You can use the q
query parameter to restrict the list of returned objects to the value specified for the id
, name
, createdBy
, or modifiedBy
attributes. The objects returned are based on a case-sensitive, partial match of these attributes. With this example, the results might include an item with an ID of part1524
and an item modified by bonapart
.
curl -i \
-X GET \
-u mobile.user@example.com:password \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects?q=part
Example of Response Header
Here's an example of the response header:
200 OK
Content-Length: 1436
Content-Type: application/json
Date: Thu, 29 Mar 2018 19:03:55 GMT
Example of Response Body
This example shows the contents of the response body in JSON format:
{
"items": [
{
"id": "bcc69c00-dc1a-4b53-8cf6-91dc973e498f",
"name": "TN062315Cust105.txt",
"user": "8c8f1a5a-e56b-494b-9a99-f03d562c1ee7",
"contentLength": 443,
"contentType": "text/plain",
"eTag": "\"1\"",
"createdBy": "mobileuser",
"createdOn": "2015-06-23T19:24:15Z",
"modifiedBy": "mobileuser",
"modifiedOn": "2015-06-23T19:24:15Z",
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/storage/collections/technicianNotes/objects/bcc69c00-dc1a-4b53-8cf6-91dc973e498f?user=8c8f1a5a-e56b-494b-9a99-f03d562c1ee7"
},
{
"rel": "self",
"href": "/mobile/platform/storage/collections/technicianNotes/objects/bcc69c00-dc1a-4b53-8cf6-91dc973e498f"
}
]
},
{
"id": "e22915f2-eb6d-48a0-86f4-ac9c0fb8b85a",
"name": "TN062015Cust101.txt",
"user": "8c8f1a5a-e56b-494b-9a99-f03d562c1ee7",
"contentLength": 206,
"contentType": "text/plain",
"eTag": "\"1\"",
"createdBy": "mobileuser",
"createdOn": "2015-06-24T02:03:48Z",
"modifiedBy": "mobileuser",
"modifiedOn": "2015-06-24T02:03:48Z",
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/storage/collections/technicianNotes/objects/e22915f2-eb6d-48a0-86f4-ac9c0fb8b85a?user=8c8f1a5a-e56b-494b-9a99-f03d562c1ee7"
},
{
"rel": "self",
"href": "/mobile/platform/storage/collections/technicianNotes/objects/e22915f2-eb6d-48a0-86f4-ac9c0fb8b85a"
}
]
}
],
"hasMore": false,
"limit": 100,
"offset": 0,
"count": 2,
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/storage/collections/technicianNotes/objects/"
},
{
"rel": "self",
"href": "/mobile/platform/storage/collections/technicianNotes/objects"
}
]
}