1. REST API for Oracle Mobile Cloud Service
  2. Tasks
  3. Storage

Store an Object by ID

put

/mobile/platform/storage/collections/{collection}/objects/{object}

This operation stores an object based on an identifier that you specify.

Example

The following example stores the contents of the file called myObj1.jpeg in the collection called myCollection. It uses the using the identifier myObj1.

curl -X PUT -H {AUTHENTICATION HEADERS} -H "Content-Length 4321" -H "Content-Type: image/jpeg" -d @myObj1.jpeg {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_WRITE
      • READ_WRITE_ALL
    • If the backend doesn't allow anonymous access, then you must be a member of the realm that's associated with the mobile backend.

Request

Supported Media Types
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"
    }
  ]
}

  • 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 a POST, then the ID was generated and returned as part of the Location 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"
    }
  ]
}
Query Parameters

  • This is the ID (not the user name) of a user. This query parameter allows a user with READ_ALL or READ_WRITE_ALL permission to access the isolated space of the user identified by the ID. Users who have READ or READ_WRITE permission can access only their own space. If you storing an object in an isolated collection, and you have READ_ALL or READ_WRITE_ALL permission, then the signed-in user is assumed unless you include this property. If you have READ_ALL or READ_WRITE_ALL permission for an isolated collection, then you must include this property to store objects in another user's 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

  • The size of the object in bytes.

  • The media type of object being stored. This is the same media type that is returned when the object is requested.

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

  • 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

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

  • 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 a PUT on the object was Mon, 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

  • The display name for the object. If you don't include the display name, the name is set to the object identifier that the POST operation generates automatically or the identifier that you supplied to the PUT operation using the {object} path parameter.

    Example - With Oracle-Mobile-Name

    If you include the Oracle-Mobile-Name header in your PUT request, like the following example:

    curl -X PUT {AUTHENTICATION HEADERS} -H "Content-Length 4321" -H "Content-Type: image/jpeg" -H "Oracle-Mobile-NAME: Banner" -d @myObj1.jpeg {HOST}/mobile/platform/storage/collections/myCollection/objects/myObj1

    Then the object's name is set to to Oracle-Mobile-Name HTTP request header value:

    {
   "id" : "myObj1",
   "name" : "Banner",
   "links" : {
       ....
   }
}

    Example - Without Oracle-Mobile-Name

    If you don't include the Oracle-Mobile-Name header in your PUT request, like the following example:

    curl -X PUT {AUTHENTICATION HEADERS} -H "Content-Length 4321" -H "Content-Type: image/jpeg" -d @myObj1.jpeg {HOST}/mobile/platform/storage/collections/myCollection/objects/myObj1

    Then the object's name will be the same value as its ID.

    {
   "id" : "myObj1",
   "name" : "myObj1",
   "links" : {
       ....
   }
}
Body ()
A body of type:
  • */*
Root Schema : schema
Back to Top

Response

Supported Media Types

200 Response

OK

The object with the given identifier was replaced in the specified collection successfully .

Body ()
Root Schema : Object
Type: object
Title: Object
Show Source
Example Response (application/json)
{
    "eTag":"\"2\"",
    "id":"profile-pic",
    "createdOn":"2014-11-20T15:57:04Z",
    "modifiedOn":"2014-11-20T15:58:09Z",
    "createdBy":"jdoe",
    "modifiedBy":"jdoe",
    "name":"Profile Picture",
    "links":[
        {
            "rel":"canonical",
            "href":"/mobile/platform/storage/collections/pictures/profile-pic"
        },
        {
            "rel":"self",
            "href":"/mobile/platform/storage/collections/pictures/profile-pic"
        }
    ],
    "contentType":"image/png",
    "contentLength":937647
}

201 Response

Created

The object was created in the specified collection successfully.

Body ()
Root Schema : Object
Type: object
Title: Object
Show Source
Example Response (application/json)
{
    "eTag":"\"1\"",
    "id":"profile-pic",
    "createdOn":"2014-11-20T15:57:04Z",
    "modifiedOn":"2014-11-20T15:57:04Z",
    "createdBy":"jdoe",
    "modifiedBy":"jdoe",
    "name":"Profile Picture",
    "links":[
        {
            "rel":"canonical",
            "href":"/mobile/platform/storage/collections/pictures/profile-pic"
        },
        {
            "rel":"self",
            "href":"/mobile/platform/storage/collections/pictures/profile-pic"
        }
    ],
    "contentType":"image/png",
    "contentLength":937647
}

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 Mobile Cloud 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 Mobile Cloud 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 from a realm that isn't associated with the mobile backend.
  2. Retrieve an object without being assigned a role that has READ or READ_WRITE access for the 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 the 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 Mobile Cloud 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 or object with the given identifier does not exist.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by Mobile Cloud 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 Mobile Cloud 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

409 Response

Conflict

This operation conflicted with another change made concurrently to the object.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by Mobile Cloud 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

411 Response

Length Required

The PUT or POST HTTP request to store an object in a collection was missing either the Content-Length or the Transfer-Encoding header.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by Mobile Cloud 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

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-Modified-Since
  • If-None-Match
  • If-Unmodified-Since
Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by Mobile Cloud 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

413 Response

Request Entity Too Large

This status is returned when you attempt to store an object that is bigger than 2147483647 bytes (approx 2GB).

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by Mobile Cloud 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
Back to Top

Examples

Example of Adding or Replacing an Object

This example shows how to use cURL to replace an object by submitting a PUT request on the REST resource. In this example, the object TN062415Cust43.txt is stored in the technicianNotes collection with the ID TN062415Cust43. If that object exists, it's replaced by TN062415Cust43.txt. If it doesn't exist, then it's added. 

curl -i \
-X PUT \ 
-u mobile.user@example.com:password \
-d @TN062415Cust43.txt \
-H "Content-Type: text/plain" \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects/TN062415Cust43

Example of Updating an Object Only if it Hasn't Been Changed by Someone Else

This example shows how to use cURL to update an object only if the object wasn't updated by someone else after you originally retrieved it. In this example, the request includes the If-Match header. The server performs the update only if the object exists and its ETag matches the ETag specified by the If-Match header. 

curl -i \
-X PUT \ 
-u mobile.user@example.com:password \
-d @TN062415Cust43.txt \
-H "If-Match: \"2\"" \
-H "Content-Type: text/plain" \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects/TN062415Cust43

Example of Adding an Object with a Specified ID Only if it Doesn't Exist

This example shows how to use cURL to add an object only if an object with the specified ID doesn't exist. In this example, the object TN062415Cust43.txt is stored in the technicianNotes collection with the ID TN062415Cust43. The If-None-Match: * header tells the server to perform the operation only if an object with the specified ID doesn't exist. 

curl -i \
-X PUT \ 
-u mobile.user@example.com:password \
-d @TN062415Cust43.txt \
-H "If-None-Match: *" \
-H "Content-Type: text/plain" \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/storage/collections/technicianNotes/objects/TN062415Cust43

Example of Response Header

Here's an example of the response header when an object is updated. In this example, an object with the ID TN062415Cust43 already exists, so the response status is 200. If the object didn't exist, then the response status would be 201. 

200 OK
Content-Length: 546
Content-Type: application/json
Date: Wed, 24 Jun 2015 03:31:24 GMT

Example of Response Body

This example shows the contents of the response body in JSON format:

{
  "id": "TN062415Cust43",
  "name": "TN062415Cust43",
  "contentLength": 443,
  "contentType": "text/plain",
  "eTag": "\"2\"",
  "createdBy": "mobileuser",
  "createdOn": "2015-06-24T03:30:13Z",
  "modifiedBy": "mobileuser",
  "modifiedOn": "2015-06-24T03:31:25Z",
  "links": [
    {
      "rel": "canonical",
      "href": "/mobile/platform/storage/collections/technicianNotes/objects/TN062415Cust43"
    },
    {
      "rel": "self",
      "href": "/mobile/platform/storage/collections/technicianNotes/objects/TN062415Cust43"
    }
  ]
}
Back to Top