Skip to content

Managing Storage Service

Storage Service API

Storage service facilitates application developers to persist mobile application specific data, such as user preferences, user contextual data, and application configuration.

Storage service does not contain business-specific data. Although you can create, update, or delete all the storage configurations using Runtime API and Admin API, there are some restrictions or conditions while using Runtime API.

Using Storage service, data can be stored at three levels:

  • Application storage: persists global configuration and application default settings.

  • User storage: persists user preferences

  • Device storage: persists installation-specific or device-specific settings.

Application Storage

If you create an application storage configuration using Runtime API, then it is accessible to all users. If you get the user storage or device storage for the application with overwrite=true query parameter, then the application level configuration gets merged into the response.

While creating or updating application storage configuration using Admin API, a __metadata property (com.sap.mobile.server.storage.admin.v1.StorageMetadata type) can be included for the application configuration to define read and write right control of the runtime API. If no ReadRoles or WriteRoles are defined for an application configuration, then the application configuration can be accessed by all users, similar to a Runtime API.

Once the ReadRoles are defined for an application configuration, then the users who have the required roles can read the application configuration using Runtime API. Similarly, only these users can get the merged application configuration, while getting the user storage or device storage configuration with overwrite=true query parameter using the Runtime API. Once the WriteRoles are defined for an application configuration, then the users who have the required roles can modify the application configuration using Runtime API.

The required roles are mandatory for reading or writing the application configuration using Runtime API, if an application storage configuration is created by Runtime API, but modified by Admin API to add ReadRoles or WriteRoles.

User Storage

Users can only access the user configurations that belong to them by using the Runtime API. When you get a user storage configuration with overwrite=true query parameter using the Runtime API, the response includes the merged application configuration, which only the users who have the required ReadRole can access it.

If a property is defined on both application storage and user storage, the one in user storage gets included in response while getting with overwrite=true query parameter. If no one is defined in the user storage, then the one on the application storage gets included in response while getting with overwrite=true query parameter.

Device Storage

User can only access the device configuration that belongs to them. While getting the device storage configuration for an application with overwrite=true query parameter using the Runtime API, the response includes the merged user storage configuration and application storage configuration, which only the users who have the required ReadRole can access it. The device storage property has the highest priority, and the application storage property has the lowest priority.

Samples for Storage Service

Note

In most mobile applications, the configuration used in the Application Storage is used as the default settings, and the end users can customize the settings in the User Storage or Device Storage level in order to provide personalized settings for the user or device. In such cases in order to make sure that only the Administrator can modify the Application Storage configuration and other users can only view it (by Application Storage Runtime API or user/device Storage Runtime API with "overwrite=true" query parameter), the application storage configuration can be configured with empty ReadRoles and Administrator WriteRoles.

Note

The application storage configuration HomeScreen is created for application mobileApp:

{
 "ApplicationId": "mobileApp",
 "HomeScreen": {
  "Menu": {
   "AutoHiding": false,
   "Style": "blue",
   "AutoHiding@odata.type": "Edm.Boolean",
   "Style@odata.type": "Edm.String"
  },
  "ShortCuts": ["Overview", "Profile"],
  "__metadata": {
   "ReadRoles": [],
   "WriteRoles": ["Administrator"]
  },
  "Menu@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageObject",
  "ShortCuts@odata.type": "Collection(Edm.String)",
  "__metadata@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageMetadata"
 },
 "HomeScreen@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageObject"
}

Only users with the Administrator role can modify these settings using Runtime API, but all other users can get these settings.

Then, the mobile application can get the settings on the device using https://<mobile_services_host>/mobileservices/application/mobileApp/Storage/v1/runtime/application/mobileApp/device/mydevice/HomeScreen?overwrite=true and fill the screen with values you received. The response body looks like:

{
 "Menu": {
  "AutoHiding": false,
  "Style": "blue"
 },
 "ShortCuts": ["Overview", "Profile"]
}

Assume the user configures the Menu/AutoHiding property value to true at device level:

PATCH https://<mobile_services_host>/mobileservices/application/mobileApp/Storage/v1/runtime/application/mobileApp/device/mydevice/HomeScreen

{
 "Menu": {
  "AutoHiding": true
 }
}

The response body of https://<mobile_services_host>/mobileservices/application/mobileApp/Storage/v1/runtime/application/mobileApp/device/mydevice/HomeScreen?overwrite=true becomes:

{
 "Menu": {
  "AutoHiding": true
 }
} {
 "Menu": {
  "AutoHiding": true,
  "Style": "blue"
 },
 "ShortCuts": ["Overview", "Profile"]
}

If you want to provide application level settings only to particular users and not all users (or settings provisioned in mobile app), then the ReadRoles can be defined, so that only users who have the Read role can get these settings.

For example, you want to provide a 2-factor authentication for managers to post some forms. Then another configuration 2factorAuth can be defined for mobileApp application with specify ReadRoles to "Manager". Then, the whole application storage for mobileApp looks like:

{
 "ApplicationId": "mobileApp",
 "HomeScreen": {
  "Menu": {
   "AutoHiding": false,
   "Style": "blue",
   "AutoHiding@odata.type": "Edm.Boolean",
   "Style@odata.type": "Edm.String"
  },
  "ShortCuts": ["Overview", "Profile"],
  "__metadata": {
   "ReadRoles": [],
   "WriteRoles": ["Administrator"]
  },
  "Menu@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageObject",
  "ShortCuts@odata.type": "Collection(Edm.String)",
  "__metadata@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageMetadata"
 },
 "2factorAuth": {
  "RequsetToken": {
   "url": "https://2factor.server/requesttoken/phone",
   "method": "POST",
   "parameters": ["username", "phone"]
  },
  "VerifyToken": {
   "url": "https://2factor.server/verify",
   "method": "POST",
   "parameters": ["token"]
  },
  "__metadata": {
   "ReadRoles": ["Manager"],
   "WriteRoles": ["Administrator"]
  },
  "RequsetToken@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageObject",
  "VerifyToken@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageObject",
  "__metadata@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageMetadata"
 },
 "HomeScreen@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageObject",
 "2factorAuth@odata.type": "#com.sap.mobile.server.storage.admin.v1.StorageObject"
}

Then, the https://<mobile_services_host>/mobileservices/application/mobileApp/Storage/v1/runtime/application/mobileApp/device/mydevice/2factorAuth?overwrite=true can return settings according to the login user's role, and mobile app can show screens and control flows according to the 2factorAuth settings.

The Application Storage configuration can also be used to persist settings for server application, if both ReadRoles and WriteRoles are defined as a role (or roles) which never belong to any users. Then, your server application can read/write these application storage configuration using a technical user who has the role.

Storage service supports two type of APIs:

  • Admin APIs

  • Runtime APIs

GET Storage Services

Retrieve new entities from application, user, and device storage sets.

Request for GET Storage Services (By Application Storage Set)

Retrieve an entity from application storage set by key.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/ApplicationStorageSet/(ApplicationId='<ApplicationId>')

Retrieve all the entities from application storage.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/ApplicationStorageSet?$<system_query_Option>

Note

Supported OData system query options are $count, $skip, $top.

HTTP Method GET

Request Parameters for GET Storage Services (By Application Storage Set)

Parameter Type Description Parameter Type
applicationId Required Key: application ID String
originName Required Origin from where the application is created. The valid value is hcpms. String
$top Optional Show only the first n elements. Integer
$skip Optional Skip the first n elements. Integer
$count Optional Allows users to request a count of the matching resources. The number is included with the resources in the response. Boolean

Response Status and Error Codes for GET Storage Services (By Application Storage Set)

Code Description
200 Entity set found in application storage set.
500 Unexpected error.
404 Entity does not exist

Request for GET Storage Services (By User Storage Set)

Retrieve an entity from user storage set by key.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/UserStorageSet(ApplicationId='<ApplicationId>', Username= '<username>')

Retrieve all entities from user storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/UserStorageSet?$<system_query_Option>

Request Parameters for GET Storage Services (By User Storage Set)

Parameter Type Description Parameter Type
username Required User name String

Response Status and Error Codes for GET Storage Services (By User Storage Set)

Code Description
200 Entity set created.
404 Entity does not exist.
500 Unknown error.

Request for GET Storage Services (By Device Storage Set)

Retrieve an entity from device storage set by key.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/DeviceStorageSet(ApplicationId='<ApplicationId>', Username= '<username>', DeviceId='<deviceId>')

Retrieve all entities from device storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/DeviceStorageSet?$<system_query_Option>

Request Parameters for GET Storage Services Services (By Device Storage Set)

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

Response Status and Error Codes for GET Storage Services Services (By Device Storage Set)

Code Description
200 Entity set created.
404 Device property already exists.
500 Unexpected error.

PUT Storage Services

Update entities from application, user, and device storage sets.

Request for PUT Storage Services (By Application Storage Set)

Update entity in application storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/ApplicationStorageSet('<ApplicationId>')

HTTP Method PUT

Request Parameters for PUT Storage Services (By Application Storage Set)

Parameter Type Description Parameter Type
applicationId Required application ID String
originName Required Origin from where the application is created. The valid value is hcpms. String

Response Status and Error Codes for PUT Storage Services (By Application Storage Set)

Code Description
200 Entity updated in application storage set.
500 Unexpected error.
404 Entity does not exist

Request for PUT Storage Services (By User Storage Set)

Update entities in user storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/UserStorageSet(ApplicationId='<ApplicationId>', Username= '<username>')

Request Parameters for PUT Storage Services (By User Storage Set)

Parameter Type Description Parameter Type
username Required User name String

Response Status and Error Codes for PUT Storage Services (By User Storage Set)

Code Description
200 Entity set updated in user storage set.
404 Entity does not exist.
500 Unexpected error.

Request for PUT Storage Services (By Device Storage Set)

Update entity in device storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/DeviceStorageSet(ApplicationId='<ApplicationId>', Username= '<username>', DeviceId='<deviceId>')

Request Parameters for PUT Storage Services (By Device Storage Set)

Parameter Type Description Parameter Type
deviceId Required Device ID String

Response Status and Error Codes for PUT Storage Services (By Device Storage Set)

Code Description
200 Entity updated in device storage set.
404 Entity does not exist.
500 Unexpected error.

POST Storage Services

Add new entity to application, user, and device storage sets.

Request for POST Storage Services (By Application Storage Set)

Create a new entity to ApplicationStorageSet

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/ApplicationStorageSet

HTTP Method POST

Response Status and Error Codes for POST Storage Services

Code Description
201 Entity created.
409 Entity already exists.
500 Unknown error.

Request for POST Storage Services (By User Storage Set)

Create a new entity in user storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/UserStorageSet

Response Status and Error Codes for POST Storage Services (By User Storage Set)

Code Description
201 Entity created.
409 Entity already exists.
500 Unexpected error.

Request for POST Storage Services (By Device Storage Set)

Create a new entity in device storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/DeviceStorageSet

Response Status and Error Codes for POST Storage Services (By Device Storage Set)

Code Description
201 Device entity created.
409 Entity already exists.
500 Unexpected error.

PATCH Storage Services

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

Request for PATCH Storage Services (By Application Storage Set)

Update entity in application storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/ApplicationStorageSet(<ApplicationId>')

HTTP Method PATCH

Request Parameters for PATCH Storage Services (By Application Storage Set)

Parameter Type Description Parameter Type
applicationId Required application ID String
originName Required Origin from where the application is created. The valid value is hcpms. String

Response Status and Error Codes for PATCH Storage Services

Code Description
200 Entity updated in application storage set.
500 Unexpected error.
404 Entity does not exist

Request for PATCH Storage Services (By User Storage Set)

Update entities in user storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originname>/Storage/v1/admin/UserStorageSet(ApplicationId='<ApplicationId>', Username= '<username>')

Request Parameters for PATCH Storage Services (By User Storage Set)

Parameter Type Description Parameter Type
username Required User name String

Response Status and Error Codes for PATCH Storage Services (By User Storage Set)

Code Description
200 Entity set is updated in the user storage set.
404 Entity does not exist.
500 Unexpected error.

Request for PATCH Storage Services (By Device Storage Set)

Update entity in device storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/DeviceStorageSet(ApplicationId='<ApplicationId>', Username= '<username>', DeviceId='<deviceId>')

Request Parameters PATCH Storage Services (By Device Storage Set)

Parameter Type Description Parameter Type
deviceId Required Device ID String

Response Status and Error Codes PATCH Storage Services (By Device Storage Set)

Code Description
200 Entity set is updated in the device storage set.
404 Entity does not exist.
500 Unexpected error.

DELETE Storage Services

Delete entities from application, user, and device storage sets.

Request for DELETE Storage Services (By Application Storage Set)

Delete entity from application storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/ApplicationStorageSet('<ApplicationId>')

HTTP Method DELETE

Request Parameters for DELETE Storage Services

Parameter Type Description Parameter Type
applicationId Required application ID String
originName Required Origin from where the application is created. The valid value is hcpms. String

Response Status and Error Codes for DELETE Storage Services

Code Description
204 Entity deleted from application storage set.
500 Unexpected error.
404 Entity does not exist.

Request for DELETE Storage Services (By User Storage Set)

Delete entities from user storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/UserStorageSet(ApplicationId='<ApplicationId>', Username= '<username>')

Request Parameters for DELETE Storage Services (By User Storage Set)

Parameter Type Description Parameter Type
username Required User name String

Response Status and Error Codes for DELETE Storage Services (By User Storage Set)

Code Description
204 Entity set is deleted from the user storage set.
404 Entity does not exist.
500 Unexpected error.

Request for DELETE Storage Services (By Device Storage Set)

Delete entities from device storage set.

URL: https://<mobile_services_host>/mobileservices/origin/<originName>/Storage/v1/admin/DeviceStorageSet(ApplicationId='<ApplicationId>', Username= '<username>', DeviceId='<deviceId>')

Request Parameters for DELETE Storage Services (By Device Storage Set)

Parameter Type Description Parameter Type
deviceId Required Device ID String

Response Status and Error Codes for DELETE Storage Services (By Device Storage Set)

Code Description
204 Entity set is deleted in the device storage set.
404 Entity does not exist.
500 Unexpected error.

Last update: August 12, 2020