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