1. REST API Reference for Oracle Mobile Cloud Enterprise - Platform APIs
  2. Tasks
  3. Storage

Return Collection Metadata

get

/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

This operation can be performed anonymously or by a user with a role that's associated with the backend.

Request

Path Parameters

  • 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"
    }
  ]
}
Header Parameters

  • 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

  • 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 the If-Match HTTP request header to ensure that the operation succeeds only if the item wasn't modified after you last requested it.

  • 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 the If-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.

  • 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

Supported Media Types

200 Response

OK

The metadata for the specified collection was returned successfully.

Headers

  • 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

  • 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

  • The Sync Client SDK uses this header.

    Allowed Values: [ "object" ]
Body ()
Root Schema : Collection
Type: object
Title: Collection
Show Source
  • Minimum Value: 0
    The total size in bytes of the objects in this collection.
  • Maximum Length: 100
    A description of the collection.
  • 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").
  • 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
  • Flag indicating if the objects are isolated by user.
Example Response (application/json)
{
    "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:

  1. Make a call without specifying the Oracle-Mobile-Backend-ID HTTP request header.
  2. Specify the user query parameter for an endpoint that isn't an object level operation for an isolated collection.
  3. Specify an incorrect value for a query parameter.
  4. Store an object with an identifier longer than the maximum allowed size.
  5. Store an object where the actual size of the object is different from what was specified in the Content-Length HTTP request header.
Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source

401 Response

Unauthorized

The user is not authenticated. The request must be made with the Authorization HTTP request header.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source

403 Response

Forbidden

This status is returned if you attempt to:

  1. Make a request with a user who doesn't have a role that's associated with the backend.
  2. Retrieve an object without being assigned a role that has READ or READ_WRITE access for a non-anonymous collection.
  3. Retrieve an object from your isolated space without being assigned a role that has READ, READ_WRITE, READ_ALL, or READ_WRITE_ALL access for the collection.
  4. Retrieve an object from another user's isolated space without being assigned a role that has READ_ALL or READ_WRITE_ALL access for the collection.
  5. Store an object without being assigned a role that has been granted READ_WRITE access for a non-anonymous collection.
  6. Store an object to your isolated space without being assigned a role that has READ_WRITE or READ_WRITE_ALL access for the collection.
  7. Store an object to another user's isolated space without being assigned a role that has READ_WRITE_ALL access for the collection.
Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source

404 Response

Not Found

A collection with the given identifier does not exist.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source

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.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source

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
Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source

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"
    }
  ]
}