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 SAP mobile service 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: ReadRole
s and WriteRole
s.
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. |