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

Return a List of Objects

get

/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

If the collection is shared and the Security_CollectionsAnonymousAccess environment policy lists the collection, then you can access this operation anonymously or as any user, regardless of assigned roles. Otherwise, you must be a user who:

  1. Has a role that's associated with the mobile backend.
  2. Has been granted access to one of the following:
    • READ
    • READ_ALL
    • READ_WRITE
    • READ_WRITE_ALL

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

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

  • 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"
        },
        ...
    ]
}

  • Use this query parameter to sort the results by name, modifiedBy, modifiedOn, createdBy, createdOn, and contentLength.

    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

  • The items that are returned are based on a case-insensitive partial match of the id, name, createdBy or modifiedBy 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" : [
       ...
   ]
    }

  • When this query parameter is present with a value of true, then the HTTP response contains the totalResults 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" : [
        ...
    ]
}

  • This is the ID (not the user name) of a user. Use * (wildcard) to get all users. This query parameter allows a user with READ_ALL/READ_WRITE_ALL permission to access another user's isolated space. A user with READ/READ_WRITE permission may access only their own space.

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

  • 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 operation completed successfully.

Headers

  • 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

  • The Sync Client SDK uses this header.

    Allowed Values: [ "collection" ]
Body ()
Root Schema : Object Array
Type: object
Title: Object Array
Show Source
  • Minimum Value: 0
    The number of items returned.
  • 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`.
  • 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
    Minimum Number of Items: 0
    Maximum Number of Items: 100
    Metadata for an object in the collection.
  • 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
  • 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.
  • 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
    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`.
Nested Schema : etags
Type: array
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`.
Show Source
Nested Schema : items
Type: array
Minimum Number of Items: 0
Maximum Number of Items: 100
Metadata for an object in the collection.
Show Source
Nested Schema : uris
Type: array
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`.
Show Source
Nested Schema : Object
Type: object
Title: Object
Show Source
  • The size of object in bytes.
  • Maximum Length: 255
    The media type of the object. For example, a JPEG image would have a media type of image/jpeg.
  • The user name for the user who created the object.
  • The date and time, in ISO 8601 format, that the object was created (for example, 2014-06-30T01:02:03Z).
  • 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.
  • 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
  • The user name for the user who last modified the object.
  • The date and time, in ISO 8601 format, that the object was last modified (for example, 2014-06-30T01:02:03Z).
  • Maximum Length: 1024
    The display name for the object.
  • For user-isolated collections, the ID of the user that the object belongs to.
Example Response (application/json)
{
    "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:

  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

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