AppSuite:Mobile API Facade
API status: In Development
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.
Requirements
The OX Facade has to be installed alongside an OX App Suite installation. It requires at least OX App Suite v7.8.4.
OX Facade API
Further information about the OX Facade API can be found at: https://documentation.open-xchange.com/components/facade/develop/
OX Mail Server-side Installation and Configuration on OX App Suite v7.8.x
This chapter describes how the backend components of OX Mail are installed and configured on the server.
Available packages
OX 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/mobile-api-facade/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
// If you have a valid maintenance subscription, please add also following repositories by replacing the credentials.
// [open-xchange-mobile-api-facade-updates]
name=Open-Xchange-mobile-api-facade-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/mobile-api-facade/stable/mobile-api-facade/updates/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/mobile-api-facade/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
// If you have a valid maintenance subscription, please add also following repositories by replacing the credentials.
// [open-xchange-mobile-api-facade-updates]
name=Open-Xchange-mobile-api-facade-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/mobile-api-facade/stable/mobile-api-facade/updates/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/stable/mobile-api-facade/DebianJessie /
// If you have a valid maintenance subscription, please add also following repositories by replacing the credentials.
$ 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/mobile-api-facade/SLE_12 mobile-api-facade
// If you have a valid maintenance subscription, please add also following repositories by replacing the credentials.
// $ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/mobile-api-facade/stable/mobile-api-facade/updates/SLE_12 mobile-api-facade-updates
$ zypper ref $ zypper install open-xchange-mobile-api-facade
Configuration OX Facade for Mobile
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 http://documentation.open-xchange.com.
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-dev-gw1.open-xchange.com:8007 timeout=100 smax=0 ttl=60 retry=60
loadfactor=50 keepalive=On route=FOX1
BalancerMember http://appsuite-dev-gw2.open-xchange.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
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.