Mobile API, towards slim mobile applications

Our former colleague Iyad writing about mobile API´s. Iyad often updates the content of his blog postings, make sure you check every once in a while the contents of his original post on: http://iyadagha.com/mobile-api-toward-slim-mobile-applications/

Most of the mobile apps we use day-to-day connect to some kind of backend using REST APIs.

The APIs used by mobile apps are mostly designed for general purposes, which means that the same APIs are used by mobile apps, the web site and all other third party applications.

This approach was at the beginning of the mobile revolution a very feasible one. Many digital companies already had a (REST) API and the traffic produced by mobile applications was at the beginning not so big that it was worth it building a specific API for them.

Now, in a time where digital companies with more than 50% mobile traffic are not a rarity anymore, it is time to rethink the way, how mobile application should use an API and to ask ourselves: Are general purpose APIs still fulfilling the needs of this ever growing kind of applications?

The answer we had at ImmobilienScout24 was no. We had several reasons, why we wanted to build a dedicated API only for the use by our mobile applications (iOS/Android). Those reasons were:

• We wanted an API which is designed, implemented and owned by the mobile teams. This would reduce dependencies to other teams and speed up the delivery process
• Our mobile applications were packed with business logic. We found, that moving a big part of the business logic from the mobile clients to a mobile API has a plenty of benefits for us (more details later)
• Reduce the network traffic by aggregating data needed for a screen with one API call and by delivering only the portion of data needed by a specific screen

Moving business logic out of the clients

In a layered mobile application design we usually have a business logic layer, a controller layer and a UI layer. On the way from business logic to the UI, data will be transformed to a kind of a presentation model which can be easily consumed from the the UI layer.
Our main idea of the mobile API is to get the presentation model directly from the API. In this case the main responsibility of the mobile client would be rendering the UI and handling the navigation.

Let me explain the idea using an example from the ImmobilienScout App.
ImmobilienScout is a German platform for finding properties. A central part of the App is the listing screen, where users can see the search results as a list of items.
There are 21 types of properties that are supported by the platform and each type could have different attributes. While an apartment has rooms and rent costs per month, an industry hall has no rooms and its rent costs are calculated per sqm. All this real estate domain knowledge was implemented in the mobile clients, in fact duplicated in both iOS and Android.

In our new approach, the mobile API deliver items for the client which are ready to display. The item contains something like an image and four different labels. The client has no idea about the data and its meaning, they are only items to be rendered just like they are.
All the computation that needs real estate domain knowledge and all the formating is done by our smart API.

The following image shows the listing screen and the needed data to render a listing item. On the right side is the output of the general API and on the left side is the one of the mobile API:

We found ourselves throwing tons of code out of our mobile apps (for most engineers a way greater feeling than writing code;) which mad the apps thinner, easier to understand and faster to iterate on.

Because the mobile API is used from both iOS and Android, business logic needs to be written only once. This saves implementation time and makes the maintenance if the code much easier.
Our API uses a CLD system, so we need only few minutes to get bugfixes on production. This helped us increase the quality of the apps and the 5 stars ratings.

UX oriented API design

A general API is usually designed around the domain model and represents the data stored in the database. The API developers try to keep the API response as general as possible, so that each single consumer of the API can make whatever it wants out of it.

A mobile API is designed around the UX/UI. In this case the simple rule is to create an API endpoint for each screen in the App, the endpoint delivers the needed presentation model for that screen. The design of the endpoint is the result of a close collaboration between the UX designers, the App developers and the API developers.

The fact that the API design depends on an ever changing UX/UI could lead to having a lot of versions of the API endpoints which immensely increase the maintenance effort.
Fortunately, we are operating in a market where the adoption rate of a new App version is very high. Within 4 weeks more than 95% of our users were on the newest version.
Hence, we supported for each endpoint the latest two versions, if a client requested an unsupported version, the API responded with a specific status code prompting the user to update the App.

In our case we had one mobile API for both iOS and Android. This works well if the UX design of both Apps is similar. Otherwise you might need a mobile API for each client.

The architecture

The architecture of our mobile API is pretty simple. It receives the requests from the mobile clients, calls the needed public APIs, compute their output and deliver the presentation model back to the client. The overhead of the extra calls to the public API was reduced by using a smart caching algorithm.

The API runs as a Node.js server within autoscaled AWS EC2 instances. The deployment is triggered automatically by the CI system using Docker and CloudFormation.

Two words about GraphQL

GraphQL is a standard that earned a lot of attention in the last months. While REST is a resource oriented approach, GraphQL is a query based approach. A client can query the part of data it needs from the server in the required structure.
GraphQL shines when multiple clients use the same api, where each client can query exactly the needed portion of data.

When we created our mobile API we took GraphQL into consideration. We ended up not using it for two reasons:

• Our mobile API is used only by our two apps. Each endpoint is designed to fulfil the need of one screen. Therefore there is no need to query the data in multiple ways
• Using GraphQL would mean a lot of changes in the networking layer in our both clients (iOS, Android). In our case, this effort is big compared with the advantage

Though, if i would rebuild everything from scratch, i would for sure use GraphQL since it gives the flexibility and the dynamics needed in modern mobile applications.

Conclusion

A dedicated mobile API could have a lot of advantages regarding the product delivery speed and the software quality. Having the responsibility of this API in the mobile team has impact on the team structure toward an end-to-end team. Running and maintaining the API creates the opportunity for a mobile team to finally practice DevOps.