1 SAP HANA Cloud Platform Mobile Services
1.5 REST API Application Development Overview
The REST Services, distributed as part of the SAP HANA Cloud Platform mobile services, enables standard HTTP client applications running in any platform to leverage mobile platform for security and push features.
Build client applications using third-party developer tools (JavaScript framework and helper libraries), native client libraries, or the libraries provided by the platform OData SDK (iOS and Android platforms only). The mobile platform enables you to manage and monitor the applications, and provides support for native push notification: Apple Push Notification service (APNS), BlackBerry Internet/Enterprise Service (BIS/BES), Google Cloud Messaging (GCM), Windows Notification Service (WNS), or Microsoft Push Notification Service (MPNS).
Application developer should first register the application connection using REST client and provide the device information, such as device type, password capability, and so on. Once registered, an application can retrieve and update the application connection settings through the REST API. You can enable or disable the push notification only after registering.
Note
You can delete an application connection using the REST API, as long as the application is not in use. Any data that is stored in the custom string of the application connection properties is lost.
During initialization, a client application can download resources (such as metadata files, multimedia files, and so on.), using the resource bundles service. After downloading resources, the application can access OData-compatible data sources through the proxy service, and receive native push notifications triggered by the gateway if push properties are configured and enabled.
This development approach supports:
● Registration (creating an application connection)
● Authentication
● Native push notification
● Usage reporting
Cloud solutions do not have a Product Availability Matrix (PAM). For more information about cloud solution product versions contact SAP representative.
1.5.1 Set Up the Development Environment
REST API applications are server-based API applications, and support mobile application development across multiple platforms, including Google Android, Apple iOS, BlackBerry, and Microsoft Windows
For detailed information about supported devices and device operating systems, see http://
service.sap.com/pam .
1.5.2 Configure Applications in Mobile Services Cockpit
Configure an application definition that enables you to manage and monitor the applications using Mobile Services Cockpit.
Defining Applications [page 21]
Create a new native, hybrid, or Web application definition, which enables you to use Mobile Services Cockpit to manage the application.
Defining Back-End Connections [page 23]
Define a back-end connection for the selected application (native, hybrid, or Web).
Configuring Form Authentication with Native SAML Providers [page 78]
Form authentication uses SAML 2.0 authentication provided by HANA Cloud Platform.
Defining Push Notifications [page 92]
Configure push-related settings for the selected application.
Uploading Client Resources [page 37]
Upload client resources, or resource bundles, for the selected application. Resource bundles are containers used by applications to download dynamic configurations, styles, or content from the SAP HANA Cloud Platform mobile services. The administrator can modify the client resource bundle settings in Mobile Services Cockpit.
Enabling Client Logs Policy [page 31]
Enable the client logs policy to upload client logs to the database.
Managing Feature Restriction Policies [page 54]
Manage a list of feature restriction policies that apply to all applications from a central location.
Feature examples include camera, printer, and push. You can add, allow, restrict, edit or delete features, and apply changes to existing hybrid applications.
1.5.2.1 Defining Applications
Create a new native, hybrid, or Web application definition, which enables you to use Mobile Services Cockpit to manage the application.
Procedure
1. In Mobile Services Cockpit, select Applications, and click . 2. Enter:
Table 30:
Field Value
Application ID Unique identifier for the application, in reverse-domain notation. This is the applica
tion or bundled identifier that is assigned or generated by the application devel
oper. The administrator uses the Application ID to register the application with SAP HANA Cloud Platform mobile services, and the client application code uses the Ap
plication ID when sending requests to the server, reverse-domain notation for the object MyApp.sap.com is com.sap.MyApp, for example.
The Application ID:
○ Must be unique
○ Must start with an alphabetic character
○ Can contain only alphanumeric characters, underscores, and periods
○ Cannot include spaces
○ Can be up to 64 characters long
Note
You cannot use these case-sensitive keywords as application identifiers: Admin, AdminData, Push, smp_cloud, resource, test-resources, resources, Scheduler, odata, applications, Connections, public, lcm.
Formatting guidelines:
○ SAP recommends that application IDs contain a minimum of two periods. For example: com.sap.mobile.app1.
○ Application IDs cannot start with a period.
○ Application IDs cannot include two consecutive periods.
Version Displays the read-only version that is set by the application developer.
Name The name:
○ Can contain only alphanumeric characters, spaces, underscores, and periods
○ Can be up to 80 characters long
Field Value
Type Application type:
○ Native – native applications, including Android, BlackBerry, iOS, Windows Mo
bile 8, and Windows 8.
○ Hybrid – Kapsel container-based applications.
○ Web – application running on SAP Mobile Platform, and securely exposed on SAP HANA Cloud Platform mobile services.
Description (Optional) The description:
○ Can contain alphanumeric characters
○ Can contain most special characters, except percent signs (%) and amper
sands (&)
○ Can be up to 255 characters long
Vendor (Optional) The vendor name:
○ Can contain only alphanumeric characters, spaces, underscores, and periods
○ Can be up to 255 characters long
Security Configuration Change this value only if you require something other than the default.
○ None – (default) anonymous authentication. No authentication challenge is sent; requests are processed anonymously.
○ Form – SAML-based SSO authentication.
○ Basic – HTTP-Basic (user name and password) authentication.
○ Certificate – X.509 certificate authentication.
○ OAuth – access token-based authentication.
Same-Origin Policy Prevent or allow your application to be accessed by cross-origin resources, while creating or updating application. By default, same-origin policy is set as enable.
○ Enable – if enabled, accessing cross-origin resources is forbidden.
○ Disable – if disabled, accessing cross-origin resources is allowed.
Note
In case of legacy applications, by default same-origin policy is set as disable to allow cross-origin access.
3. Click Save.
Note
Application-related options, such as Back End, Client Policies, Push, and so on, appear in Mobile Services Cockpit only after an application has been successfully created.
1.5.2.2 Defining Back-End Connections
Define a back-end connection for the selected application (native, hybrid, or Web).
Context
A back-end connection is a connection to the data source, also called the enterprise information system (EIS).
SAP HANA Cloud Platform mobile services supports one primary endpoint per application ID. However, an administrator can create multiple secondary endpoints for other services used by the application; SAP HANA Cloud Platform mobile services treats these additional endpoints as proxy connections. For applications that access a Web service containing relative URLs, add the relative paths to enable SAP HANA Cloud Platform mobile services to handle requests correctly.
Procedure
1. Create a new application.
2. Select Back End, and enter:
Field Value
Back-End URL The URL (back-end connection, or service document) the application uses to access business data on the back-end system or service. The service document URL is the document
destination you assign to the service.
The URL must include a trailing slash to avoid triggering a redirection of the URL, and losing important HTTP header details. This is especially important when configuring the application with security, such as SSOToken and Certificates, and when Rewrite URL is enabled.
Examples:
http://mobile<account_name>-<tenantname>.hana.ondemand.com/
help/abc/app1/opg/sdata/TESTFLIGHT/
http://mobile<account_name>-<tenantname>.hana.ondemand.com/sap/opu/odata/RMTSAMPLE/
Proxy Type Select either:
○ Internet – HTTP destinations use Internet proxy. Back-end systems are in the public domain and accessible to everyone. For example, www.google.com.
○ OnPremise – back-end systems are behind a firewalls and HTTP destinations use SAP HANA cloud connector to connect to these systems.
Field Value
Note
If the proxy type is Internet, the back-end URL can be either a gateway or a cloud connector URL; if the proxy type is OnPremise, the back-end URL must be a cloud connector URL.
Authentication Type SAP HANA Cloud Platform uses the HTTPS protocol to integrate into the existing security landscape without disruption.
Select one of these authentication types:
○ Principal Propagation – allows destinations to forward the identity of on-demand users to the Cloud connector, and then to the back-end of the relevant premise system. An on-demand user need not provide his or her identity for each connection to an on-premise system via the same Cloud connector.
Note
Proxy Type must be OnPremise; otherwise, the destination cannot be saved.
○ No Authentication – back ends do not require credentials for authentication. Your destination is provided direct access to the relevant on-premise service.
○ SAPAssertionSSO – configure the back-end system to accept SAP assertion tickets that are signed by a trusted x.509 key pair.
○ Basic Authentication – enter user name and password credentials to authenticate.
○ Client Certification Authentication – prepare a client certificate and have it signed by a SAP HANA Cloud Platform mobile services certification authority (CA). The client certificate must be trusted by back-end systems.
Note
Proxy type must be Internet, the back-end URL must use HTTPS, and you must provide both keystore and truststore parameters.
Maximum Connections
The number of back-end connections that are available for connection pooling for this application. The larger the pool, the larger the number of possible parallel connections to this specific connection. For primary endpoints, the default range is 1-199 connections. Factors to consider when resetting this property:
○ The expected number of concurrent users of the application.
○ The load that is acceptable to the back-end system.
○ The load that the underlying hardware and network can handle.
Increase the maximum number of connections only if SAP HANA Cloud Platform mobile services hardware can support the additional parallel connections, and if the underlying hardware and network infrastructure can handle it.
Rewrite Mode Select one of:
○ Rewrite URL on HANA Mobile Server – in request and response messages, SAP HANA Cloud Platform mobile services replaces all back-end URLs with the server URL. The Rewrite URL format for Web type applications – https://<HMCServerHost>/
<ApplicationID>.
Field Value
○ Rewrite URL on Backend – the back end rewrites the URLs. SAP HANA Cloud Platform mobile services forwards its host name and port to the back end as an HTTP header, and the back end creates the URL to retrieve back-end entities. To expose the full URL to clients, the server passes the endpoint in an X-SMP-ENDPOINTNAME header. For example:
○ Back-end URL – http://ldcigm3.wdf.sap.corp:50057/sap/opu/odata/sap/
FINCUSTFACTSHEET/
○ URL exposed to clients – http://smphost:port/sap/opu/odata/sap/
FINCUSTFACTSHEET/
○ URL format for Web type applications – https://<HMCServerHost>/<Part of Backend>?X-SMP-APPID=<ApplicationID>. For example: https://mobiletest-xxxxxxxxx.new.ondemand.com/sap/bc/ui5_ui5/ui2/ushell/shells/abap/
FioriLaunchpad.html?X-SMP-APPID=xxxxxBE.
Note
○ When you switch the rewrite mode configuration to or from "Rewrite URL on Backend" in the Mobile Services Cockpit, it is required that the application developer is aware of the change. He/she should accordingly change the base URL of the application in case of online and offline mobile application scenarios.
○ If the rewrite mode is selected as "Rewrite URL on Backend", the base path of the URL must correspond to the path of the backend URL. In other rewrite modes, the base path must contain the Application ID (as shown above in the example).
○ It is recommended that you do not change the rewrite mode arbitrarily, without reconfiguring the mobile application information.
○ Depending on the configuration of other applications configured in your account, it might not be possible to detect from the browser URL which exact application is targetted. Therefore it is always recommended you append the application ID as a URL parameter to the start URL when opening an application in a browser: https://server/<appid>?X-SMP-APPID=<appid>. For example: https://server/webapp?X-SMP-APPID=webapp.
In the case where the URL needs other query parameters, you can simply append it to the end of the URL: https://server/webapp?
other=parameter&needed=true&X-SMP-APPID=webapp"
Via HCP HTML5 App:
○ If selected, the host name is sent to the back end in the HTTP header <X-FORWARDED-FOR>.
○ If not selected, the host name is sent to the back end in the standard HTTP header
"Host".
Field Value
Note
When the SAP HANA Cloud Platform mobile services sends a request to fetch data from the back end, an HTTP header includes host information. This mechanism causes failures when connecting via a HTML5 application hosted on HANA Cloud Platform. In case of failures, select Via HCP HTML5 App. The request host is then sent in the x-forwarded-for header, which is used by HTML5 applications, and sent as the host header to a back end.
Web type applications: For transparent onboarding of Web type applications that are using the Rewrite URL on Backend option, use the URL parameter X-SMP-APPID to specify the requested Web Application. Keep in mind:
○ You can specify any application using the X-SMP-APPID parameter.
○ If the parameter is used without an existing application, no application is used.
○ If the parameter is used without an existing Web application, no application is used.
○ If the parameter is used for an application without a valid endpoint for the called path, no application is used.
○ No Rewriting – request and response messages are not modified; SAP HANA Cloud Platform mobile services passes messages directly between clients and the back end.
The URL format for Web type applications – https://<HMCServerHost>/
<ApplicationID>
Note
To enable applications using an external back end to run offline, you must select one of the rewrite options.
Relative Paths If an application requires data from a back end that uses relative URLs, you must configure those relative URL patterns in Mobile Services Cockpit. SAP HANA Cloud Platform mobile services rewrites the relative URLs to include the Connection ID (connection name), enabling access to the back-end data. For example, a Web service application requests an HTML page named abc.html, which contains the relative URLs /sap/bc and /sap/public/bc in its src or href tags.
When a request is made, SAP HANA Cloud Platform mobile services rewrites the relative URLs contained in the response, so that subsequent requests (to these relative URLs in the response) can be processed correctly. For example, if "webApp" is the connection name and the response contains the relative URLs /sap/bc,/sap/public/bc; SAP HANA Cloud Platform mobile services rewrites these relative URLS to /webApp/sap/bc,/
webApp/sap/public/bc. Without the relative URLs, the request cannot be processed.
To add relative paths, you can either enter one relative URL per table row (for
example, /sap/bc in one row, and /sap/public/bc in another); or you can enter a comma-delimited list of relative URLs in one table row (for example, /sap/bc,/sap/
public/bc), and the URLs are redistributed to separate rows after you Save.
Field Value
Note
To use the Relative Path option, you must select Rewrite URL in HANA Mobile Server option in Rewrite Mode.
Keystore Location (For mutual SSL authentication) If the back-end URL begins with HTTPS and the proxy type is Internet, either:
○ Select a certificate from the list, or
○ Click Upload and Delete Certificates, and select a certificate to upload.
Keystore Password (For mutual SSL authentication) A valid password for the keystore you selected.
User Name (Optional) The user name to access the back-end system.
Password (Required if you set the user name) The password to access the back end.
Use Default JDK Truststore
To validate remote HTTPS certificates, select to use the default JDK truststore certificate.
3. (Optional) Under Back-End Connections, view additional connections, or add new connections.
a. To add back-end connections (secondary endpoints) in the server, select New.
b. Enter values for the new back-end connection, using the values shown above.
c. Select Save. The new back-end connection is added to the list.
You can maintain the list of server-level back-end connections (including all the connections in SAP HANA Cloud Platform mobile services), and of application-specific back-end connections. Application-specific back-end connections are the secondary connections that are enabled for an application; by default, no secondary connections are enabled. You must explicitly enable additional back-end connections for an application. Users who are registered to an application can access only these back-end connections. If a user attempts to access a back-end connection (request-response) that is not enabled for an application, a 403, Forbidden, error is thrown.
4. Select Application-specific Connections to show the back-end connections that are enabled for the application.
Select Server-level Connections to show all available connections for the server. Select additional connections for the application to enable them.
Note
○ You can authenticate multiple back ends using various authentication provider options in the back-end security profile.
○ If the back-end system issues a “302 Redirect” or "307 Redirect" response, which means it is redirecting the request to a different URL, then you must also add the target URL to the list of application-specific connections.
1.5.2.3 Configuring Form Authentication with Native SAML Providers
Form authentication uses SAML 2.0 authentication provided by HANA Cloud Platform.
Context
By default, HANA Cloud Platform uses SAP ID service to authenticate users against SAP user accounts and SCN accounts. The HANA Cloud Operator configures the native Form/SAML 2.0 at the account level. All applications configured with Form authentication use this native provider. However, each subscriber can further customize an identity provider (IdP) configuration with their own on-premise SAML 2.0 provider in the HANA Cloud Platform cockpit.
Procedure
1. To use an on-premise SAML provider, follow these instructions in the HANA Cloud Platform documentation: https://help.hana.ondemand.com/help/frameset.htm?
dc618538d97610148155d97dcd123c24.html. If you are using the native IdP, continue to step 2.
2. In Mobile Services Cockpit:
a. Select Applications, and click . b. For Security Configuration, choose Form.
1.5.2.4 Defining Push Notifications
Configure push-related settings for the selected application.
The push listener service provided with the server allows back-end systems to send native notifications to devices. Application developers must enable push notification code in applications to use this option.
Android Push Notifications [page 35]
To enable client applications to receive Google Cloud Messaging (GCM) notifications, configure Android push notifications for the selected application.
Apple Push Notifications [page 35]
To enable client applications to receive APNS notifications, configure Apple push notifications for the selected application.
BlackBerry Push Notifications [page 35]
To enable client applications to receive BES/BIS notifications, configure BlackBerry push notifications for the selected application.
Windows Push Notifications [page 36]
To enable the back-end servers connected with SAP HANA Cloud Platform mobile services to send toast, tile, badge, and raw updates to Windows desktop and tablet application users, configure
To enable the back-end servers connected with SAP HANA Cloud Platform mobile services to send toast, tile, badge, and raw updates to Windows desktop and tablet application users, configure