Return Collection Metadata
/mobile/platform/storage/collections/{collection}
This operation returns metadata about the collection. The collection must be available through the backend that the request is associated with.
Example
The following example retrieves the metadata for the myCollection
collection.
curl -X GET {AUTHENTICATION HEADERS} {HOST}/mobile/platform/storage/collections/myCollection
Permissions
Anyone who has access to the backend has access to this operation.
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" } ] }
-
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-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. -
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 metadata for the specified collection was returned successfully.
-
Cache-Control: string
This HTTP response header describes how the result may be cached. The
no-cache
portion ensures that authorization is respected.Cache-Control: public, no-cache
-
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
-
Oracle-Mobile-Sync-Resource-Type: string
The Sync Client SDK uses this header.
Allowed Values:[ "object" ]
object
Collection
-
contentLength:
integer
Minimum Value:
0
The total size in bytes of the objects in this collection. -
description:
string
Maximum Length:
100
A description of the collection. -
eTag:
string
Each collection has an ETag value. This value changes each time the collection metadata is updated. The value includes the starting and ending quotation marks (for example, "2").
-
id:
string
Minimum Length:
1
Maximum Length:100
The collection's name. This is the value that is used in the URI to access the collection. -
links:
array links
Minimum Number of Items:
0
The links that you can use to explore the resource. -
userIsolated:
boolean
Flag indicating if the objects are isolated by user.
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.
{
"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"
}
],
"id":"pictures"
}
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:
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.
412 Response
Precondition Failed
This status is returned when the collection with the given identifier exists, but the operation failed because of one or more of the following conditions:
If-Match
If-None-Match
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
This example shows how to use cURL to retrieve metadata about 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
Example of Response Header
Here's an example of the response header:
200 OK
Content-Length: 295
Content-Type: application/json
Date: Thu, 29 Mar 2018 21:43:46 GMT
Example of Response Body
This example shows the contents of the response body in JSON format:
{
"id": "technicianNotes",
"description": "Technicians' personal notes.",
"userIsolated": true,
"contentLength": 0,
"eTag": "\"1.0\"",
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/storage/collections/technicianNotes"
},
{
"rel": "self",
"href": "/mobile/platform/storage/collections/technicianNotes"
}
]
}