Skip to content

Accessing Storage Service

Runtime APIs

Used by mobile application to access settings at all the three storage levels during runtime.

The runtime API can be accessed by both application authentication and origin authentication URL patterns. Currently, the runtime APIs only addressed origin authentication URL pattern. For example,

  • Origin authentication URL pattern: https://<mobile services host>/mobileservices/origin/<originname>/Storage/v1/runtime/application/<applicationId>/currentuser/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>[?overwrite=<overwrite>]

  • Application authentication URL pattern: https://<mobile services host>/mobileservices/application/<applicationId>/<serviceName>/.... Request is authenticated by application’s security configuration (configured in Mobile Services cockpit).

If mobile application only needs to access default settings, it can directly use application storage level API and retrieve the settings. If mobile application allows their end users to create user or device specific settings, it uses user storage or device storage APIs. If there are no user level or device level settings, then the GET operation response includes only application level settings.The device storage API merges settings in both Application storage and user storage.

HTTP Method Action
GET GET Storage Service
POST POST Storage Service
PUT PUT Storage Service
DELETE DELETE Storage Service
PATCH PATCH Storage Service

GET Storage Service

Retrieve a mobile data storage service based on application configuration, user property, or device property.

Request for GET Storage Service (By Application Configuration)

URL: https://<mobile services host>/mobileservices/origin/<originName>/Storage/v1/runtime/application/<applicationId>/global/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

HTTP Method GET

Request Parameters for GET Storage Service (By Application Configuration)

Parameter Type Description Parameter Type
applicationId Required Application identifier. String
OriginName Required Origin from where the application is created. The valid value is hcpms. String
configurationName Optional Configuration name. String
propName Optional Property name. The propName, propNameLv2 or propNameLvN are arbitrary in Request URL, as long as the property exists in the configuration or parent property value. If one of the properties does not exist, it returns 404 code for PUT/PATCH/DELETE/GET methods. String

Note

Any special characters in the configuration name and property name includes must be correctly encoded in URL.

Request Example for GET Storage Service (By Application Configuration)

`GET` /application/appID1/endpoints/__metadata/readRoles
  * get the read roles of endpoints configuration.
`GET` /application/appID1/endpoints/ep1/url
  * get the url value of ep1 endpoint.

Response Status and Error Codes for GET Storage Service (By Application Configuration)

Code Description
200 Property value, which may be a JSON object, a primitive value, or any array except for JSON one.
403 No permission to access a configuration.
404 Specified application or property not exists.
500 Unknown error.

Request for GET Storage Service (By User Name)

Retrieve user-specific configuration.

URL: https://<mobile services host>/mobileservices/origin/<originname>/Storage/v1/runtime/application/<applicationId>/currentuser/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for GET Storage Service (By User Name)

Parameter Type Description Parameter Type
user name Required User name String
Overwrite Optional Whether result needs to merge with application-level data. The default value is true. Boolean

Response Status and Error Codes for GET Storage Service (By User Name)

Code Description
200 User property created.
403 No permission to access a configuration.
404 Specified application or property does not exists.
500 Unknown error.

Note

Set the overwrite property for a user-level configuration to true, to overwrite an application-level configuration. The current level and its parent level configuration is merged by using the overwrite property.

Request for GET Storage Service (By Device Name)

Retrieve a device-specific configuration or property.

URL: https://<mobile services host>/mobileservices/origin/<originname>/Storage/v1/runtime/application/<applicationId>/device/<deviceId>/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for GET Storage Service (By Device Name)

Parameter Type Description Parameter Type
deviceId Required Unique identifier for device type String
Overwrite Optional Whether result needs to merge with application-level data. The default value is true. Boolean
Code Description
200 Device property created.
403 No permission to access a configuration.
404 Device property already exists.
500 Unknown error.

PUT Storage Service

Update mobile data storage service based on application configuration, user property, or device property.

Request for PUT Storage Service (By Application Configuration)

URL: https://<mobile services host>/mobileservices/origin/<originName>/Storage/v1/runtime/application/<applicationId>/global/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

HTTP Method PUT

Request Parameters for PUT Storage Service (By Application Configuration)

Parameter Type Description Parameter Type
applicationId Mandatory Application identifier. String
originName Mandatory Origin from where the application is created. The valid value is hcpms. String
configurationName Optional Configuration name. String
propName Optional Property name. The propName, propNameLv2 or propNameLvN are arbitrary in Request URL, as long as the property exists in the configuration or parent property value. If one of properties does not exist, it returns 404 code for PUT/PATCH/DELETE/GET methods. String

Note

It replaces the stored configurations by the one provided in request body.

Response Status and Error Codes for PUT Storage Service (By Application Configuration)

Code Description
204 Updated application configuration successfully.
403 No permission to access a configuration.
409 Specified application or property not exists.
500 Unknown error.

Request for PUT Storage Service (By User Name)

Update a user-specific configuration or property.

URL: https://<mobile services host>/mobileservices/origin/<originname>/Storage/v1/runtime/application/<applicationId>/currentuser/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for PUT Storage Service (By User Name)

Parameter Type Description Parameter Type
userName Mandatory User name String

Response Status and Error Codes for PUT Storage Service (By User Name)

Code Description
204 Updated user property successfully.
403 Cannot access other user's configuration.
404 Specified application or property does not exists.
500 Unknown error.

Request for PUT Storage Service (By Device Name)

Create a device-specific configuration or property.

Details about the creator of the device configuration is stored internally. The storage service API verifies the creator information before (??) accessing device configuration.

URL: https//<mobile services host>/mobileservices/origin/<originName>/Storage/v1/runtime/application/<applicationId>/device/<deviceId>/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for PUT Storage Service (By Device Name)

Parameter Type Description Parameter Type
deviceId Required Unique identifier for device type String
Code Description
201 Device created.
403 No permission to access a configuration.
409 Property already exists.
500 Unknown error.

Note

The authenticated user name implicitly accesses the information; however, the user name and device ID identify the device-level configuration.

POST Storage Service

Create a mobile data storage service based on application configuration, user property, or device property.

Request for POST Storage Service (By Application Configuration)

Create an application configuration, which is a JSON object that includes arbitrary properties. Each configuration can include a "__metadata" property which includes two properties for access control: ReadRoles and WriteRoles.

URL: https://<mobile services host>/mobileservices/origin/<originName>/Storage/v1/runtime/application/<applicationId>/global/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

HTTP Method POST

Request Parameters for POST Storage Service (By Application Configuration)

Parameter Type Description Parameter Type
applicationId Required Application identifier String
configurationName Optional Configuration name String
originName Required Origin from where the application is created. The valid value is hcpms. String
propName Optional Property name. The propName, propNameLv2, or propNameLvN are arbitrary in Request URL, as long as the property exists in the configuration or parent property value. The property name must exists in the request URL, otherwise, a 404 code for PUT/PATCH/DELETE/GET methods is returned. String

Request Example for POST Storage Service (By Application Configuration)

This example code creates a configuration for an application named "test1".

`POST` Storage/v1/runtime/application/test1

{
  "endpoints":{
    "ep1": { "url": "http://endpoint1"},
    "ep2": { "url": "http://endpoint2"}
  },
  "push": {
    "APN": { "host": "www.apple.com",
             "user": "useraaa",
             "pwd": "pwd"},
    "GCM": { "host": "www.google.com",
             "token": "ABABABA"},
    "__metadata": {
             "readRoles": ["Role1", "Role2"],
             "writeRoles": ["Role1"] }
  }

After creating the application configuration, you can use property names to add a new endpoint for the application.

{
  "endpoints":{
    "ep1": { "url": "http://endpoint1"},
    "ep2": { "url": "http://endpoint2"},
 "ep3": { "url": "http://endpoint3"},
  },
  "push": {
    "APN": { "host": "www.apple.com",
             "user": "useraaa",
             "pwd": "pwd"},
    "GCM": { "host": "www.google.com",
             "token": "ABABABA"},
    "__metadata": {
             "readRoles": ["Role1", "Role2"],
             "writeRoles": ["Role1"] }
  }
}  

Response Status and Error Codes for POST Storage Service (By Application Configuration)

Code Description
201 Property created.
403 No permission to access a configuration.
409 Property already exists.
500 Unknown error.

Request for POST Storage Service (By User Name)

Create a user-specific configuration.

URL: https://<mobile services host>/mobileservices/origin/<originName>/Storage/v1/runtime/application/<applicationId>/currentuser/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for POST Storage Service (By User Name)

Parameter Type Description Parameter Type
user name Required User name String

Request Example for POST Storage Service (By User Name)

`POST` /application/appID1/user/ab01/ep1

{ "authenticationType": "NoAuth" }

Response Status and Error Codes for POST Storage Service (By User Name)

Code Description
201 Property created.
403 Cannot access other user configuration.
409 Property already exists.
500 Unknown error.

Note

The user name must be the authenticated user name, otherwise, the service returns error code 403.

Request for POST Storage Service (By Device Name)

Create a device-specific configuration or property.

Details about the creator of the device configuration is stored internally. The storage service API verifies the creator information before (??) accessing device configuration.

URL: https//<mobile services host>/mobileservices/origin/<originName>/Storage/v1/runtime/application/<applicationId>/device/<deviceId>/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for POST Storage Service (By Device Name)

Parameter Type Description Parameter Type
deviceId Required Unique identifier for device type String
Code Description
201 Device created.
403 No permission to access a configuration.
409 Property already exists.
500 Unknown error.

Note

The authenticated user name implicitly accesses the information; however, the user name and device ID identify the device-level configuration.

PATCH Storage Service

Merge a mobile data in the existing storage service based on application configuration, user property, or device property.

Request for PATCH Storage Service (By Application Configuration)

The partial configuration after merged with the existing configuration is stored in the database.

URL: https://<mobile services host>/mobileservices/origin/<originName>/Storage/v1/runtime/application/<applicationId>/global/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

HTTP Method PATCH

Request Parameters for PATCH Storage Service (By Application Configuration)

Parameter Type Description Parameter Type
applicationId Required Application identifier. String
prop Required Partial property value, which can be part of a JSON object, a primitive value, or any array except a JSON array. Property
originName Mandatory Origin from where the application is created. The valid value is hcpms. String
configurationName Optional Configuration name. String
propName Optional Property name. The propName, propNameLv2 or propNameLvN are arbitrary in Request URL, as long as the property exists in the configuration or parent property value. If the property does not exist, it returns 404 code for PUT/PATCH/DELETE/GET methods. String

Request Example for PATCH Storage Service (By Application Configuration)

In this example, the following code is in application configuration 'appID1'

{
  "endpoints":{
    "ep2": { "url": "http://newEndpoint2" }
  },
  "push": {
    "BES": { "host": "www.blackberry.com",
             "user": "useraaa",
             "pwd": "pwd"}
  }
}

After existing and new configuration is merged, the new configuration is stored in the database as:

{
  "endpoints":{
    "ep1": { "url": "http://endpoint1"},
    "ep2": { "url": "http://newEndpoint2"}
  },
  "push": {
    "APN": { "host": "www.apple.com",
             "user": "useraaa",
             "pwd": "pwd"},
    "GCM": { "host": "www.google.com",
             "token": "ABABABA"},
    "BES": { "host": "www.blackberry.com",
             "user": "useraaa",
             "pwd": "pwd"},
    "__metadata": {
             "readRoles": ["Role1", "Role2"],
             "writeRoles": ["Role1"] }
  }
}  

Response Status and Error Codes for PATCH Storage Service (By Application Configuration)

Code Description
204 Updated application configuration or property.
403 No permission to access a configuration.
404 Specified application configuration does not exist. .
500 Unknown error.

Request for PATCH Storage Service (By User Name)

Partially update a user-specific configuration or property.

URL: https://<mobile services host>/mobileservices/origin/<originname>/Storage/v1/runtime/application/<applicationId>/currentuser/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for PATCH Storage Service (By User Name)

Parameter Type Description Parameter Type
userName Required User name String

Response Status and Error Codes for PATCH Storage Service (By User Name)

Code Description
204 Updated user property.
403 Cannot access other user's configuration.
409 Property already exists.
500 Unknown error

Request for PATCH Storage Service (By Device Name)

Partially update a device-specific configuration or property.

URL: https://<mobile services host>/mobileservices/origin/<originName>/Storage/v1/runtime/application/<applicationId>/device/<deviceId>/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for PATCH Storage Service (By Device Name)

Parameter Type Description Parameter Type
deviceId Required Unique identifier for device type String
Code Description
204 Updated device property.
403 No permission to access a configuration.
409 Property already exists.
500 Unknown error.

DELETE Storage Service

Delete a mobile data storage service based on application configuration, user property, or device property.

Request for DELETE Storage Service (By Application Configuration)

Delete application configuration or property.

URL: https://<mobile services host>/mobileservices/origin/<originName>/Storage/v1/runtime/application/<applicationId>/global/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

HTTP Method DELETE

Request Parameters for DELETE Storage Service (By Application Configuration)

Parameter Type Description Parameter Type
applicationId Mandatory Application identifier String
originName Required Origin from where the application is created. The valid value is hcpms. String
configurationName Optional Configuration name String
propName Optional Property name. The propName, propNameLv2 or propNameLvN are arbitrary in Request URL, as long as the property exists in the configuration or parent property value. If one of properties does not exist, it returns 404 code for PUT/PATCH/DELETE/GET methods. String

Response Status and Error Codes for DELETE Storage Service (By Application Configuration)

Code Description
204 Deleted of application configuration or property.
403 No permission to access a configuration.
404 Specified application configuration does not exists.
500 Unknown error.

Request for DELETE Storage Service (By User Name)

Delete a user-specific configuration or property.

URL: https://<mobile services host>/mobileservices/origin/<originname>/Storage/v1/runtime/application/<applicationId>/currentuser/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for DELETE Storage Service (By User Name)

Parameter Type Description Parameter Type
userName Mandatory User name String

Response Status and Error Codes for DELETE Storage Service (By User Name)

Code Description
204 Deleted user property successfully.
403 Cannot access other user's configuration.
404 User property already exists.
500 Unknown error

Request for DELETE Storage Service (By Device Name)

Delete a device-specific configuration or property.

URL: https://<mobile services host>/mobileservices/origin/<originname>/Storage/v1/runtime/application/<applicationId>/device/<deviceId>/<configurationName>/<propName>/<propNameLv2>/<propNameLvN>

Request Parameters for DELETE Storage Service (By Device Name)

Parameter Type Description Parameter Type
deviceId Mandatory Unique identifier for device type String

Response Status and Error Codes for DELETE Storage Service (By Device Name)

Code Description
204 Updated device property.
403 No permission to access a configuration.
404 Specified application or device property already exists.
500 Unknown error.

Last update: August 12, 2020