Return an Object
/mobile/platform/storage/collections/{collection}/objects/{object}
This operation retrieves an object and its metadata from a collection based on the object identifier.
Example
The following example retrieves the contents of the object with identifier myObj1
that is stored in the collection myCollection
.
curl -X GET {AUTHENTICATION HEADERS} {HOST}/mobile/platform/storage/collections/myCollection/objects/myObj1
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" } ] }
-
object: string
The ID of the object being accessed. If the object was stored via a
PUT
, then this is the ID that was provided in the URI, and if the object was stored via aPOST
, then the ID was generated and returned as part of theLocation
HTTP response header.When looking at the object metadata, this parameter corresponds to the value for the
id
attribute:{ "id": "profile-pic", "name": "Profile Picture", "contentLength": 937647, "contentType": "image/png", "eTag": "\"2\"", "createdBy": "jdoe", "createdOn": "2014-11-20T15:57:04Z", "modifiedBy": "jdoe", "modifiedOn": "2014-11-20T15:58:09Z", "links": [ { "rel": "canonical", "href": "/mobile/platform/storage/collections/pictures/objects/profile-pic" }, { "rel": "self", "href": "/mobile/platform/storage/collections/pictures/objects/profile-pic" } ] }
-
user(optional): string
This is the ID (not the user name) of a user. This query parameter allows a user with
READ_ALL
orREAD_WRITE_ALL
permission to access the isolated space of the user identified by the ID. Users who haveREAD
orREAD_WRITE
permission can access only their own space. If you storing an object in an isolated collection, and you haveREAD_ALL
orREAD_WRITE_ALL
permission, then the signed-in user is assumed unless you include this property. If you haveREAD_ALL
orREAD_WRITE_ALL
permission for an isolated collection, then you must include this property to store objects in another user's 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
-
If-Match(optional): string
The request completes successfully only if the ETag of the corresponding item matches one of the values specified in this HTTP request header.
Example - Optimistic Locking
Assume that the last time you requested an item, its ETag was
"2"
. You can use theIf-Match
HTTP request header to ensure that the operation succeeds only if the item wasn't modified after you last requested it. -
If-Modified-Since(optional): string
Date and time in HTTP-date format. The request completes successfully only if the object was modified after the date specified in this HTTP request header.
Example - Get Only if Newer
You can use this header to reduce the amount of data that you pull down to your client. For example, assume that the last time that you retrieved the object its timestamp was
Mon, 30 Jun 2014 19:43:31 GMT
. The following request retrieves the object only if the object was modified after the last time you retrieved it.curl -X GET {AUTHENTICATION HEADERS} -H 'If-Modified-Since: Mon, 30 Jun 2014 19:43:31 GMT' -d @me.jpeg {HOST}/mobile/platform/storage/collections/myCollection/objects/myObj1
-
If-None-Match(optional): string
The request completes successfully only if the ETag of the corresponding item does not match one of the values specified by this HTTP request header.
Example - Get Only if Newer
You can use this header to reduce the amount of data that gets pulled down to your client. For example, assume that the last time you accessed an item, its ETag was
"2"
. You can use theIf-None-Match
HTTP request header to ensure that the operation succeeds only if the item has been modified since you last requested it.Example - Put if Absent
When the value of the
If-None-Match
request header is a wildcard (*
), then the request succeeds only when an ETag is not present. -
If-Unmodified-Since(optional): string
Date and time in HTTP-date format. The request completes successfully only if the object wasn't modified after the date specified in this HTTP request header.
Example - Optimistic Locking
Assuming the timestamp for the last time you did a
GET
or aPUT
on the object wasMon, 30 Jun 2014 19:43:31 GMT
, you can use the this HTTP request header to ensure that the operation succeeds only if no one modified the object after that time.curl -X PUT {AUTHENTICATION HEADERS} -H 'If-Unmodified-Since: Mon, 30 Jun 2014 19:43:31 GMT' -d @myObj1.jpeg {HOST}/mobile/platform/storage/collections/myCollection/objects/myObj1
-
Oracle-Mobile-Content-Disposition(optional): string
This header enables you to request the value of the
Content-Disposition
HTTP response header.Example - Force Browser to Show "Save As" Dialog
The following request causes the response to contain the HTTP response header
Content-Disposition
with the valueattachment; filename="myObj1.jpeg"
. This header value causes a browser to show the Save As dialog instead of trying to render the object.curl -X GET {AUTHENTICATION HEADERS} -H 'Oracle-Mobile-Content-Disposition: attachment; filename="myObj1.jpeg"' " {HOST}/mobile/platform/storage/collections/myCollection/objects/myObj1
-
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. -
Range(optional): string
This header allows you to request a subset of bytes.
Examples
bytes=0-99
(first 100 bytes)bytes=100-199
(second 100 bytes)bytes=-100
(last 100 bytes)bytes=0-99,-100
(first 100 and last 100 bytes)
Response
- application/json
- */*
200 Response
OK
The entire object and metadata with the given identifier was successfully retrieved from the specified collection.
-
Accept-Ranges: string
This header indicates that byte ranges may be provided when requesting an object resource.
-
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
-
Content-Disposition: string
This HTTP response header is returned if the request was made with the
Oracle-Mobile-Content-Disposition
request header. The value for the response is the same as the request value. -
Content-Length: string
The size of object in bytes.
-
Content-Type: string
The media type of the object. For example, a JPEG image would have a media type of
image/jpeg
. -
ETag: string
Each item has an ETag value. This value changes each time the item is updated. The value includes the starting and ending quotation marks (for example,
"2"
). You can use an ETag value with the following HTTP request headers:If-Match
IF-None-Match
-
Last-Modified: string
The date and time when the resource was last modified. This date is in RFC-1123 format.
Example
Fri, 29 Aug 2014 12:34:56 GMT
-
Oracle-Mobile-Canonical-Link: string
A relative URI that you can use to uniquely reference this object.
-
Oracle-Mobile-Created-By: string
The user name of the user who created the object.
-
Oracle-Mobile-Created-On: string
The date and time, in ISO 8601 format (for example,
2014-06-30T01:02:03Z
), when the object was created. -
Oracle-Mobile-Modified-By: string
The user name of the user who last modified the object.
-
Oracle-Mobile-Modified-On: string
The date and time, in ISO 8601 format (for example,
2014-06-30T01:02:03Z
), when the object was last modified. -
Oracle-Mobile-Name: string
The display name for the object.
-
Oracle-Mobile-Self-Link: string
A relative URI that you can use to uniquely reference this object within the specified isolation level.
-
Oracle-Mobile-Sync-Expires: string
This header is used by the Sync Client SDK.
-
Oracle-Mobile-Sync-No-Store: string
This header is used by the Sync Client SDK.
206 Response
Partial Content
This response contains the range(s) requested in the Range
HTTP request header.
-
Accept-Ranges: string
This header indicates that byte ranges may be provided when requesting an object resource.
-
Content-Disposition: string
This HTTP response header is returned if the request was made with the
Oracle-Mobile-Content-Disposition
request header. The value for the response is the same as the request value. -
Content-Length: string
The size of object in bytes.
-
Content-Type: string
The media type of the object. For example, a JPEG image would have a media type of
image/jpeg
. -
ETag: string
Each item has an ETag value. This value changes each time the item is updated. The value includes the starting and ending quotation marks (for example,
"2"
). You can use an ETag value with the following HTTP request headers:If-Match
IF-None-Match
-
Last-Modified: string
The date and time when the resource was last modified. This date is in RFC-1123 format.
Example
Fri, 29 Aug 2014 12:34:56 GMT
-
Oracle-Mobile-Canonical-Link: string
A relative URI that you can use to uniquely reference this object.
-
Oracle-Mobile-Created-By: string
The user name of the user who created the object.
-
Oracle-Mobile-Created-On: string
The date and time, in ISO 8601 format (for example,
2014-06-30T01:02:03Z
), when the object was created. -
Oracle-Mobile-Modified-By: string
The user name of the user who last modified the object.
-
Oracle-Mobile-Modified-On: string
The date and time, in ISO 8601 format (for example,
2014-06-30T01:02:03Z
), when the object was last modified. -
Oracle-Mobile-Name: string
The display name for the object.
-
Oracle-Mobile-Self-Link: string
A relative URI that you can use to uniquely reference this object within the specified isolation level.
-
X-MCS-Sync-Resource-Type: string
Allowed Values:
[ "file" ]
304 Response
Not Modified
This status is returned when an object with the given identifier exists in the specified collection, but the operation failed because of one or more of the following conditions:
If-Modified-Since
If-None-Match
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(optional):
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
-
Array of:
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(optional):
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
-
Array of:
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(optional):
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
-
Array of:
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 or object 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(optional):
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
-
Array of:
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(optional):
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
-
Array of:
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.
412 Response
Precondition Failed
An object with the given identifier in the specified collection exists, but the operation failed because of one or more of the following conditions:
If-Match
If-Unmodified-Since
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(optional):
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
-
Array of:
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.
416 Response
Requested Range Not Satisfiable
This error occurs when either the start or end of a range request is larger than the size of the object that you are requesting.
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(optional):
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
-
Array of:
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 an Object
This example shows how to use cURL to retrieve an object and its metadata from a collection by submitting a GET request on the REST resource.
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/e22915f2-eb6d-48a0-86f4-ac9c0fb8b85a \
Example of Retrieving an Object Only if It Has Changed
This example shows how to use the If-None-Match
header to prevent re-fetching an object if it hasn't changed. The server returns a 304 Not Modified
if the ETags match.
curl -i \
-X GET \
-u mobile.user@example.com:password \
-H "If-None-Match: \"2\"" \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects/e22915f2-eb6d-48a0-86f4-ac9c0fb8b85a \
Example of Retrieving Part of an Object (Chunking Data)
If your client needs to get a large object, such as a video file, you can use the Range
header to return the data in chunks. Using this strategy, you can start streaming a video, or start displaying the contents of a long list before you fetch the whole object. In this example, the server returns the first 100 and the last 100 bytes.
curl -i \
-X GET \
-u mobile.user@example.com:password \
-H "Range: bytes=0-99,-100" \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects/e22915f2-eb6d-48a0-86f4-ac9c0fb8b85a \
Example of Response Header
Here's an example of the response header:
200 OK Accept-Ranges: bytes Content-Length: 59 Content-Type: text/plain Date: Thu, 29 Mar 2018 20:21:55 GMT ETag: "4" Last-Modified: Wed, 24 Jun 2017 02:38:12 GMT Oracle-Mobile-Canonical-Link: /mobile/platform/storage/collections/technicianNotes/objects/8365be63-3ab3-4fd8-bd51-35b05aed101d?user=8c8f1a5a-e56b-494b-9a99-f03d562c1ee7 Oracle-Mobile-Created-By: username Oracle-Mobile-Created-On: 2015-06-24T02:38:12Z Oracle-Mobile-Modified-By: username Oracle-Mobile-Name: TN062315Cust43.txt Oracle-Mobile-Self-Link: /mobile/platform/storage/collections/technicianNotes/objects/8365be63-3ab3-4fd8-bd51-35b05aed101d
Example of Response Body
This example shows the contents of the retrieved object, which is in text format:
Two large dogs in house. Hard to get behind the appliance.