Difference between revisions of "AppSuite:Mobile API Facade"

 
(44 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Stability-experimental}}
+
= Mobile API Facade =
  
= IN PROGRESS - OX Facade for Mobile =
+
== General Information ==
 +
 
 +
The Mobile API Facade is a server component that brings the new native mobile mail apps together with the OX App Suite. We’ve built the façade based on the technology used and proven in the OX App Suite middleware. The facade is developed in Java, utilizing the OSGI Framework.
 +
 
 +
The Facade provides offline friendly HTTP interface by doing the work, the connections through the HTTP API, to the OX App Suite and providing only the data the offline capable clients need. In some cases multiple requests to the OX App Suite are combined into one for its clients.The facade also offers a method to tell the clients that information on the server haven’t changed since the last time the client asked for it. This reduces the amount of data to transmit to the clients under certain circumstances, especially important in mobile networks were bandwidth (and overall traffic) is limited. Thanks to facade some functionality can be shared among all clients and need only get implemented once. One example for this is the teaser text extraction, and HTML mail handling in general.The facade also provides a pluggable authentication system. In the default case, login request are just forwarded to the middleware. In more advanced use-cases, the login request is forwarded to IDM of the customer and an OX session is created from the access token from the IDM. For clients this is pretty straightforward.
 +
 
 +
== License information ==
 +
 
 +
=== Used 3rd party licenses ===
  
== General Information ==
+
In addition to the 3rd party software [https://www.open-xchange.com/legal/licenses-ox-app-suite/ used by AppSuite], the Mobile API Facade uses to following libraries:
  
The Mobile API Facade is an additional server component for OX App Suite which is required for OX Mail App v2.0. The component proxies the requests of apps to the middleware and optimizes them for usage by mobile clients by limiting their number and size.
+
* [https://www.open-xchange.com/fileadmin/user_upload/images/portfolio/license/MIT_License_Generic.pdf Project Lombok (The MIT License]
 +
* [https://www.open-xchange.com/fileadmin/user_upload/images/portfolio/license/MIT_License_Generic.pdf Semver4J (The MIT License)]
  
 
== Requirements ==
 
== Requirements ==
  
The OX Facade has to be installed alongside an OX App Suite installation. It requires at least OX App Suite v7.8.4.
+
The Mobile API Facade has to be installed alongside an OX App Suite installation. It requires at least OX App Suite v7.8.4.
 +
 
 +
== Version Matrix ==
 +
{|border="2" rules="all" align="left">
 +
|-
 +
|colspan=1|'''OX App Suite Core Version'''
 +
|colspan=1|'''Mobile API Facade Version'''
 +
|colspan=1|'''Version-Stream'''
 +
|-
 +
|v7.8.4
 +
|v1.0.x
 +
|stable-1.0
 +
|-
 +
|v7.10.1
 +
|v1.4.x
 +
|stable-1.4
 +
|-
 +
|v7.10.2
 +
|v1.6.x
 +
|stable-1.6
 +
|-
 +
|v7.10.3
 +
|v1.8.x
 +
|stable-1.8
 +
|-
 +
|}
  
== OX Facade API ==
+
== Mobile API Facade API ==
  
Further information about the OX Facade API can be found at:
+
Further information about the Mobile API Facade API can be found at:
https://documentation.open-xchange.com/components/facade/develop/
+
https://documentation.open-xchange.com/components/facade/1.0.0/
  
= OX Mail Server-side Installation and Configuration on OX App Suite v7.8.x =
+
= OX Mail Server-side Installation and Configuration on OX App Suite v7.10.3 =
  
 
This chapter describes how the backend components of OX Mail are installed and configured on the server.
 
This chapter describes how the backend components of OX Mail are installed and configured on the server.
Line 22: Line 56:
 
== Available packages ==
 
== Available packages ==
  
OX Facade is available with the following backend packages:
+
Mobile API Facade is available with the following backend packages:
  
* ''open-xchange-mobile-push-certificates'' - Certificates for cloud-based push notifications
+
* ''open-xchange-mobile-api-facade''
* ''open-xchange-mailapp-backend'' - The main server components for OX Mail
 
* ''open-xchange-mobile-push-plugin'' - Provides Push functionality
 
  
 
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.
 
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.
Line 34: Line 66:
 
Add the following repositories to your Open-Xchange yum configuration:
 
Add the following repositories to your Open-Xchange yum configuration:
  
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=[CUSTOMERID:PASSWORD]|backend/updates}}
+
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=rhelname|pc2v=RHEL6|mobile-api-facade}}
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mail/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=[CUSTOMERID:PASSWORD]|mail|mailapp}}
 
  
and run
+
$ yum install open-xchange-mobile-api-facade
 +
 +
=== Redhat Enterprise Linux 7 or CentOS 7 ===
  
  $ yum install open-xchange-mobile-push-certificates open-xchange-mailapp-backend open-xchange-mobile-push-plugin
+
Add the following repositories to your Open-Xchange yum configuration:
 +
 
 +
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=rhelname|pc2v=RHEL7|mobile-api-facade}}
 +
 
 +
$ yum install open-xchange-mobile-api-facade
  
 +
=== Debian GNU/Linux 9.0 ===
 +
 +
Add the following repositories to your Open-Xchange apt configuration:
 +
 +
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=debianname|pc2v=DebianStretch|mobile-api-facade}}
 +
 +
$ apt-get update
 +
$ apt-get install open-xchange-mobile-api-facade
 +
 +
=== Debian GNU/Linux 10.0 ===
 +
 +
Add the following repositories to your Open-Xchange apt configuration:
 +
 +
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=debianname|pc2v=DebianBuster|mobile-api-facade}}
 +
 +
$ apt-get update
 +
$ apt-get install open-xchange-mobile-api-facade
 +
 +
=== SUSE Linux Enterprise Server 12 ===
 +
 +
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=susename|pc2v=SLE_12|mobile-api-facade}}
 +
 +
$ zypper ref
 +
$ zypper install open-xchange-mobile-api-facade
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
= OX Mail Server-side Installation and Configuration on OX App Suite 7.8.x and 7.10.x =
 +
 +
If you want to update an older version of OX Mobile API Facade to the latest maintenance release, add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>. Replace VERSION with the link for the stream of versions as listed above in the version matrix (e.g. stable-1.8) or a specific version you are using (e.g. 1.8.3).
 +
 +
This chapter describes how the backend components of OX Mail are installed and configured on the server.
 +
 +
== Available packages ==
 +
 +
Mobile API Facade is available with the following backend packages:
 +
 +
* ''open-xchange-mobile-api-facade''
 +
 +
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.
 +
 +
=== Redhat Enterprise Linux 6 or CentOS 6 ===
 +
 +
Add the following repositories to your Open-Xchange yum configuration:
 +
 +
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=rhelname|pc2v=RHEL6|mobile-api-facade}}
 +
 +
$ yum install open-xchange-mobile-api-facade
 +
 
=== Redhat Enterprise Linux 7 or CentOS 7 ===
 
=== Redhat Enterprise Linux 7 or CentOS 7 ===
  
 
Add the following repositories to your Open-Xchange yum configuration:
 
Add the following repositories to your Open-Xchange yum configuration:
  
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=[CUSTOMERID:PASSWORD]|backend/updates}}
+
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=rhelname|pc2v=RHEL7|mobile-api-facade}}
  {{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mail/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=[CUSTOMERID:PASSWORD]|mail|mailapp}}
+
 
 +
  $ yum install open-xchange-mobile-api-facade
  
and run
+
=== Debian GNU/Linux 8.0 ===
  
$ yum install open-xchange-mobile-push-certificates open-xchange-mailapp-backend open-xchange-mobile-push-plugin
+
Add the following repositories to your Open-Xchange apt configuration:
  
=== Debian GNU/Linux 7.0 (Wheezy) (valid until v7.8.2) ===
+
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianJessie|mobile-api-facade}}
 +
 
 +
$ apt-get update
 +
$ apt-get install open-xchange-mobile-api-facade
 +
 
 +
=== Debian GNU/Linux 9.0 ===
  
 
Add the following repositories to your Open-Xchange apt configuration:
 
Add the following repositories to your Open-Xchange apt configuration:
  
  {{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.8.2|pc2n=debianname|pc2v=DebianWheezy|pc3v=[CUSTOMERID:PASSWORD]|backend/updates}}
+
  {{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianStretch|mobile-api-facade}}
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mail/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=[CUSTOMERID:PASSWORD]|mail|mailapp}}
 
  
and run
+
$ apt-get update
 +
$ apt-get install open-xchange-mobile-api-facade
 +
 
 +
=== Debian GNU/Linux 10.0 ===
 +
 
 +
Add the following repositories to your Open-Xchange apt configuration:
 +
 
 +
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianBuster|mobile-api-facade}}
  
 
  $ apt-get update
 
  $ apt-get update
  $ apt-get install open-xchange-mobile-push-certificates open-xchange-mailapp-backend open-xchange-mobile-push-plugin
+
  $ apt-get install open-xchange-mobile-api-facade
 +
 
 +
=== SUSE Linux Enterprise Server 12 ===
 +
 
 +
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=susename|pc2v=SLE_12|mobile-api-facade}}
 +
 
 +
$ zypper ref
 +
$ zypper install open-xchange-mobile-api-facade
 +
 
 +
= Configuration Mobile API Facade =
 +
 
 +
== Introduction ==
 +
 
 +
To be able to use the native mail apps the Mobile API Facade needs to be installed in front of the OX App Suite middleware. This document describes how to configure the Mobile API Facade.
 +
 
 +
The Mobile API Facade stores its configuration in the files <code>/opt/open-xchange/mobile-api-facade/etc/facade.properties</code> (the global configuration) and in <code>/opt/open-xchange/mobile-api-facade/etc/mobile-api-facade-config.yml</code> (hostname specific configuration). Both files support the same configuration properties as can be seen on https://documentation.open-xchange.com/components/mobile-api-facade/config/1.8/.
 +
 
 +
== Connection to the OX App Suite Middleware ==
 +
 
 +
After installation of the facade package ("open-xchange-mobile-api-facade") the property <code>com.openexchange.mobile.api.facade.MiddlewareBaseUrl</code> needs to get set to the correct URL. This property needs to be explicitly configured by the administrator. It has no default value. Its possible to connect the Mobile API Facade directly to a middleware process, but this is highly discouraged. The Mobile API Facade should always connect to a middleware process through a load balancer.
 +
 
 +
An example:
 +
 
 +
com.openexchange.mobile.api.facade.MiddlewareBaseUrl=https://appsuite.example.com/appsuite/api
 +
 
 +
After this configuration the open-xchange-mobile-api-facade needs to get restarted.
 +
 
 +
== Proxy configuration ==
 +
 
 +
<Proxy balancer://oxcluster_facade>
 +
        Order Allow,Deny
 +
        Allow from all
 +
        BalancerMember http://appsuite-middleware1.example.com:8007 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=FOX1
 +
        BalancerMember http://appsuite-middleware2.example.com:8007 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=FOX2
 +
 +
        ProxySet stickysession=JSESSIONID|jsessionidscolonpathdelim=On
 +
        SetEnv proxy-initial-not-pooled
 +
        SetEnv proxy-sendchunked
 +
</Proxy>
 +
 +
ProxyPass /services/api-facade balancer://oxcluster_facade/services/api-facade
 +
 
 +
== Traffic compression ==
 +
 
 +
The clients need to exchange a lot of data with the facade to accomplish the task of a mail client. This traffic can be compressed. Clients add the header "Accept-Encoding: gzip,deflate" by default. For this to work the Apache web server in front of the facade needs to handle this as the facade itself is not returning compressed response bodies.
 +
 
 +
For Apache HTTPD <code>{mod_deflate}</code> needs to be enabled and the following line needs to be added to your virtual host:
 +
 
 +
AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css
 +
text/xml application/xml text/x-js application/x-javascript application/json
 +
 
 +
== Starting/Stopping the Facade Service ==
 +
 
 +
The facade runs as its own service independent of the normal OX App Suite middleware. For this on Debian-based system it can be started with
 +
 
 +
service open-xchange-mobile-api-facade start
 +
 
 +
It can be stopped with
 +
 
 +
service open-xchange-mobile-api-facade stop
 +
 
 +
== Rereading configuration from disk ==
 +
 
 +
All configuration properties which are marked as reloadable can be configured without restarting the Mobile API Facade by using the <code>reloadconfiguration</code> utility. As the Mobile API Facade runs in its own process you need to tell <code>reloadconfiguration</code> to connect it instead of the Middleware. This can be done by:
 +
 
 +
reloadconfiguration -p 1100
 +
 
 +
== Ports ==
 +
 
 +
As the Mobile API Facade is its own process it also has its own JMX port and its own RMI port. The default JMX port is 9995 and the default RMI port is 1100. These ports needs to be explicitly specified to the command line tools using either JMX or RMI.
 +
 
 +
== Configuration of Mobile API Facade behavior ==
 +
 
 +
This can be configured in facade.properties and mobile-api-facade-config.yml.
 +
 
 +
=== Multiple host names ===
 +
 
 +
The Mobile API Facade supports multiple host names on one instance, that are configured differently. These can be configured in mobile-api-facade-config.yml. This file in YAML format. Beware that indentation is really important in YAML.
 +
 
 +
<pre>
 +
[ host name ]:
 +
[ properties, you want to configure ]
 +
 
 +
[ host name ]:
 +
[ properties, you want to configure ]
 +
 
 +
...
 +
</pre>
 +
 
 +
The allowed properties are the same as allowed in facade.properties. You can find a complete list at https://documentation.open-xchange.com/components/mobile-api-facade/config/1.8/.
 +
 
 +
=== Custom properties ===
 +
 
 +
It's possible to configure custom properties to be returned to clients. This is usefull to return special configurations to your clients. Custom properties are key/attribute values under the "customProperties" key.
 +
 
 +
Example:
 +
 
 +
<pre>
 +
appsuite.example.com:
 +
    customProperties:
 +
        custom.specific.property: true
 +
        custom.specific.property.2: "value"
 +
</pre>
 +
 
 +
=== Client specific configuration ===
 +
 
 +
By implementing the  client specific feature the above configuration possibilities got extended. We now have to use YAML lists for each host name. This allows to add multiple different configurations to one host configuration. You can add a list of matchers in the "matches" key to a host configuration. The first "matches" entry for a given host name that matches to the given User-Agent header sent by the client will be used. Further evaluation is not done at runtime. Configuration properties need to be on the same indentation level as the "matches" key. These host configurations inherit a default configuration from the configuration in facade.properties. Otherwise they need to be complete. They don't inherit configuration properties from other places.
 +
 
 +
<pre>
 +
[ host name ]:
 +
- matches:
 +
  [ matchers, you want to match against ]
 +
  [ properties, you want to configure ]
 +
- matches:
 +
  [ matchers, you want to match against ]
 +
  [ properties, you want to configure ]
 +
...
 +
</pre>
 +
 
 +
Example:
 +
 
 +
The iOS version supported in the beginning was iOS 9 and up. At some point in time due to technical reasons support for iOS 9 and 10 was dropped and the application supported iOS 11 and up. When you now want to update all installations on iOS 11 and up to the latest app version but leave old installations in intact you can use the force upgrade feature of the apps. Keep in mind that the matching process stops when the first match is found. If no match was found the default configuration is used.
 +
 
 +
<pre>
 +
appsuite.example.com:
 +
- matches:
 +
  platform: 'iOS'
 +
  osVersion: '11.0-'
 +
          brand: 'OpenXchange'
 +
  com.openexchange.mobile.api.facade.minimumClientVersion.ios: '11.2'
 +
  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
 +
- matches:
 +
  platform: 'iOS'
 +
  osVersion: '-10.99'
 +
  brand: 'OpenXchange'
 +
  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
 +
</pre>
 +
 
 +
=== Matchers ===
  
=== Debian GNU/Linux 8.0 (Jessie) ===
+
Several matchers are possible. All match against values in the User-Agent header.
  
Add the following repositories to your Open-Xchange apt configuration:
+
- platform: This matcher allows it to match only for "Android" or "iOS"
 +
- version: This matcher checks against the application version. This is not the marketing version displayed in the About screen of the application.
 +
- osVersion: The version of the operating system on the client device
 +
- device: This matches against the exact device model.
 +
    brand: This matches against the brand name of the app. By default this is "OpenXchange". Versions specifically branded for customers have a unique brand name.
  
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3v=[CUSTOMERID:PASSWORD]|backend/updates}}
+
=== Version matching ===
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mail/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=[CUSTOMERID:PASSWORD]|mail|mailapp}}
 
  
and run
+
For the matchers 'version' and 'osVersion' we allow to match concrete versions or version ranges. When adding a matcher with a concrete version, just put the version number as string attribute after the matcher name.
  
$ apt-get update
+
<pre>
$ apt-get install open-xchange-mobile-push-certificates open-xchange-mailapp-backend open-xchange-mobile-push-plugin
+
appsuite.example.com:
 +
- matches:
 +
  platform: 'iOS'
 +
  osVersion: '11.0'
 +
  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
 +
</pre>
  
 +
When matching a range we are always matching inclusive. You can either use a closed range, a range with a given start value and an end value, or an open range with either a start value or an end value. Keep in mind that to match all versions lower then '11.0' you need use a probably non-existing version number like '10.99'.
  
=== SUSE Linux Enterprise Server 11 (valid until v7.8.2) ===
+
<pre>
 +
appsuite.example.com:
 +
- matches:
 +
  platform: 'iOS'
 +
  osVersion: '11.0-'
 +
  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: true
 +
- matches:
 +
  platform: 'iOS'
 +
  osVersion: '-10.99'
 +
  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
 +
</pre>
  
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.8.2|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates}}
+
== Debugging ==
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mail/stable|pc2n=susename|pc2v=SLES11|mail|mailapp}}
 
  
$ zypper ref
+
In order to check whether installation went successful you may want to run
$ zypper install open-xchange-mobile-push-certificates open-xchange-mailapp-backend open-xchange-mobile-push-plugin
 
  
=== SUSE Linux Enterprise Server 12 ===
+
  $ curl -v http://localhost:8007/services/api-facade/v1/version
  
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates}}
+
That should return a JSON string like this:
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mail/stable|pc2n=susename|pc2v=SLE_12|mail|mailapp}}
 
  
$ zypper ref
+
<code>
$ zypper install open-xchange-mobile-push-certificates open-xchange-mailapp-backend open-xchange-mobile-push-plugin
+
{"version":"1.6.8","commitHash":"9e90d6072407b73c3e05b86ce724962af1a3de61","middlewareVersion":"7.10.2-Rev15"}
 +
</code>

Latest revision as of 14:43, 22 April 2020

Mobile API Facade

General Information

The Mobile API Facade is a server component that brings the new native mobile mail apps together with the OX App Suite. We’ve built the façade based on the technology used and proven in the OX App Suite middleware. The facade is developed in Java, utilizing the OSGI Framework.

The Facade provides offline friendly HTTP interface by doing the work, the connections through the HTTP API, to the OX App Suite and providing only the data the offline capable clients need. In some cases multiple requests to the OX App Suite are combined into one for its clients.The facade also offers a method to tell the clients that information on the server haven’t changed since the last time the client asked for it. This reduces the amount of data to transmit to the clients under certain circumstances, especially important in mobile networks were bandwidth (and overall traffic) is limited. Thanks to facade some functionality can be shared among all clients and need only get implemented once. One example for this is the teaser text extraction, and HTML mail handling in general.The facade also provides a pluggable authentication system. In the default case, login request are just forwarded to the middleware. In more advanced use-cases, the login request is forwarded to IDM of the customer and an OX session is created from the access token from the IDM. For clients this is pretty straightforward.

License information

Used 3rd party licenses

In addition to the 3rd party software used by AppSuite, the Mobile API Facade uses to following libraries:

Requirements

The Mobile API Facade has to be installed alongside an OX App Suite installation. It requires at least OX App Suite v7.8.4.

Version Matrix

OX App Suite Core Version Mobile API Facade Version Version-Stream
v7.8.4 v1.0.x stable-1.0
v7.10.1 v1.4.x stable-1.4
v7.10.2 v1.6.x stable-1.6
v7.10.3 v1.8.x stable-1.8

Mobile API Facade API

Further information about the Mobile API Facade API can be found at: https://documentation.open-xchange.com/components/facade/1.0.0/

OX Mail Server-side Installation and Configuration on OX App Suite v7.10.3

This chapter describes how the backend components of OX Mail are installed and configured on the server.

Available packages

Mobile API Facade is available with the following backend packages:

  • open-xchange-mobile-api-facade

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

Redhat Enterprise Linux 6 or CentOS 6

Add the following repositories to your Open-Xchange yum configuration:

 [open-xchange-mobile-api-facade]
name=Open-Xchange-mobile-api-facade
baseurl=https://software.open-xchange.com/products/mobile-api-facade/stable-1.8/mobile-api-facade/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

$ yum install open-xchange-mobile-api-facade

Redhat Enterprise Linux 7 or CentOS 7

Add the following repositories to your Open-Xchange yum configuration:

 [open-xchange-mobile-api-facade]
name=Open-Xchange-mobile-api-facade
baseurl=https://software.open-xchange.com/products/mobile-api-facade/stable-1.8/mobile-api-facade/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

$ yum install open-xchange-mobile-api-facade

Debian GNU/Linux 9.0

Add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/mobile-api-facade/stable-1.8/mobile-api-facade/DebianStretch /
$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

Debian GNU/Linux 10.0

Add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/mobile-api-facade/stable-1.8/mobile-api-facade/DebianBuster /
$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

SUSE Linux Enterprise Server 12

$ zypper ar https://software.open-xchange.com/products/mobile-api-facade/stable-1.8/mobile-api-facade/SLE_12 mobile-api-facade
$ zypper ref
$ zypper install open-xchange-mobile-api-facade






OX Mail Server-side Installation and Configuration on OX App Suite 7.8.x and 7.10.x

If you want to update an older version of OX Mobile API Facade to the latest maintenance release, add the following entry to /etc/apt/sources.list.d/open-xchange.list. Replace VERSION with the link for the stream of versions as listed above in the version matrix (e.g. stable-1.8) or a specific version you are using (e.g. 1.8.3).

This chapter describes how the backend components of OX Mail are installed and configured on the server.

Available packages

Mobile API Facade is available with the following backend packages:

  • open-xchange-mobile-api-facade

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

Redhat Enterprise Linux 6 or CentOS 6

Add the following repositories to your Open-Xchange yum configuration:

 [open-xchange-mobile-api-facade]
name=Open-Xchange-mobile-api-facade
baseurl=https://software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

$ yum install open-xchange-mobile-api-facade

Redhat Enterprise Linux 7 or CentOS 7

Add the following repositories to your Open-Xchange yum configuration:

 [open-xchange-mobile-api-facade]
name=Open-Xchange-mobile-api-facade
baseurl=https://software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

$ yum install open-xchange-mobile-api-facade

Debian GNU/Linux 8.0

Add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade/DebianJessie /
$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

Debian GNU/Linux 9.0

Add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade/DebianStretch /
$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

Debian GNU/Linux 10.0

Add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade/DebianBuster /
$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

SUSE Linux Enterprise Server 12

$ zypper ar https://software.open-xchange.com/products/mobile-api-facade/VERSION/mobile-api-facade/SLE_12 mobile-api-facade
$ zypper ref
$ zypper install open-xchange-mobile-api-facade

Configuration Mobile API Facade

Introduction

To be able to use the native mail apps the Mobile API Facade needs to be installed in front of the OX App Suite middleware. This document describes how to configure the Mobile API Facade.

The Mobile API Facade stores its configuration in the files /opt/open-xchange/mobile-api-facade/etc/facade.properties (the global configuration) and in /opt/open-xchange/mobile-api-facade/etc/mobile-api-facade-config.yml (hostname specific configuration). Both files support the same configuration properties as can be seen on https://documentation.open-xchange.com/components/mobile-api-facade/config/1.8/.

Connection to the OX App Suite Middleware

After installation of the facade package ("open-xchange-mobile-api-facade") the property com.openexchange.mobile.api.facade.MiddlewareBaseUrl needs to get set to the correct URL. This property needs to be explicitly configured by the administrator. It has no default value. Its possible to connect the Mobile API Facade directly to a middleware process, but this is highly discouraged. The Mobile API Facade should always connect to a middleware process through a load balancer.

An example:

com.openexchange.mobile.api.facade.MiddlewareBaseUrl=https://appsuite.example.com/appsuite/api

After this configuration the open-xchange-mobile-api-facade needs to get restarted.

Proxy configuration

<Proxy balancer://oxcluster_facade>
        Order Allow,Deny
        Allow from all
        BalancerMember http://appsuite-middleware1.example.com:8007 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=FOX1
        BalancerMember http://appsuite-middleware2.example.com:8007 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=FOX2

        ProxySet stickysession=JSESSIONID|jsessionidscolonpathdelim=On
        SetEnv proxy-initial-not-pooled
        SetEnv proxy-sendchunked
</Proxy>

ProxyPass /services/api-facade balancer://oxcluster_facade/services/api-facade

Traffic compression

The clients need to exchange a lot of data with the facade to accomplish the task of a mail client. This traffic can be compressed. Clients add the header "Accept-Encoding: gzip,deflate" by default. For this to work the Apache web server in front of the facade needs to handle this as the facade itself is not returning compressed response bodies.

For Apache HTTPD {mod_deflate} needs to be enabled and the following line needs to be added to your virtual host:

AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css 
text/xml application/xml text/x-js application/x-javascript application/json

Starting/Stopping the Facade Service

The facade runs as its own service independent of the normal OX App Suite middleware. For this on Debian-based system it can be started with

service open-xchange-mobile-api-facade start

It can be stopped with

service open-xchange-mobile-api-facade stop

Rereading configuration from disk

All configuration properties which are marked as reloadable can be configured without restarting the Mobile API Facade by using the reloadconfiguration utility. As the Mobile API Facade runs in its own process you need to tell reloadconfiguration to connect it instead of the Middleware. This can be done by:

reloadconfiguration -p 1100

Ports

As the Mobile API Facade is its own process it also has its own JMX port and its own RMI port. The default JMX port is 9995 and the default RMI port is 1100. These ports needs to be explicitly specified to the command line tools using either JMX or RMI.

Configuration of Mobile API Facade behavior

This can be configured in facade.properties and mobile-api-facade-config.yml.

Multiple host names

The Mobile API Facade supports multiple host names on one instance, that are configured differently. These can be configured in mobile-api-facade-config.yml. This file in YAML format. Beware that indentation is really important in YAML.

[ host name ]:
	[ properties, you want to configure ]

[ host name ]:
	[ properties, you want to configure ]

...

The allowed properties are the same as allowed in facade.properties. You can find a complete list at https://documentation.open-xchange.com/components/mobile-api-facade/config/1.8/.

Custom properties

It's possible to configure custom properties to be returned to clients. This is usefull to return special configurations to your clients. Custom properties are key/attribute values under the "customProperties" key.

Example:

appsuite.example.com:
    customProperties:
        custom.specific.property: true
        custom.specific.property.2: "value"

Client specific configuration

By implementing the client specific feature the above configuration possibilities got extended. We now have to use YAML lists for each host name. This allows to add multiple different configurations to one host configuration. You can add a list of matchers in the "matches" key to a host configuration. The first "matches" entry for a given host name that matches to the given User-Agent header sent by the client will be used. Further evaluation is not done at runtime. Configuration properties need to be on the same indentation level as the "matches" key. These host configurations inherit a default configuration from the configuration in facade.properties. Otherwise they need to be complete. They don't inherit configuration properties from other places.

[ host name ]:
	- matches:
		  [ matchers, you want to match against ]
		  [ properties, you want to configure ]
	- matches:
		  [ matchers, you want to match against ]
		  [ properties, you want to configure ]
	...

Example:

The iOS version supported in the beginning was iOS 9 and up. At some point in time due to technical reasons support for iOS 9 and 10 was dropped and the application supported iOS 11 and up. When you now want to update all installations on iOS 11 and up to the latest app version but leave old installations in intact you can use the force upgrade feature of the apps. Keep in mind that the matching process stops when the first match is found. If no match was found the default configuration is used.

appsuite.example.com:
	- matches:
		  platform: 'iOS'
		  osVersion: '11.0-'
          brand: 'OpenXchange'
	  com.openexchange.mobile.api.facade.minimumClientVersion.ios: '11.2'
	  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
	- matches:
		  platform: 'iOS'
		  osVersion: '-10.99'
		  brand: 'OpenXchange'
	  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false

Matchers

Several matchers are possible. All match against values in the User-Agent header.

- platform: This matcher allows it to match only for "Android" or "iOS" - version: This matcher checks against the application version. This is not the marketing version displayed in the About screen of the application. - osVersion: The version of the operating system on the client device - device: This matches against the exact device model.

   brand: This matches against the brand name of the app. By default this is "OpenXchange". Versions specifically branded for customers have a unique brand name.

Version matching

For the matchers 'version' and 'osVersion' we allow to match concrete versions or version ranges. When adding a matcher with a concrete version, just put the version number as string attribute after the matcher name.

appsuite.example.com:
	- matches:
		  platform: 'iOS'
		  osVersion: '11.0'
	  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false

When matching a range we are always matching inclusive. You can either use a closed range, a range with a given start value and an end value, or an open range with either a start value or an end value. Keep in mind that to match all versions lower then '11.0' you need use a probably non-existing version number like '10.99'.

appsuite.example.com:
	- matches:
		  platform: 'iOS'
		  osVersion: '11.0-'
	  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: true
	- matches:
		  platform: 'iOS'
		  osVersion: '-10.99'
	  com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false

Debugging

In order to check whether installation went successful you may want to run

  $ curl -v http://localhost:8007/services/api-facade/v1/version

That should return a JSON string like this:

{"version":"1.6.8","commitHash":"9e90d6072407b73c3e05b86ce724962af1a3de61","middlewareVersion":"7.10.2-Rev15"}