Most contemporary mobile applications have the same version accessible from the web browser. Both of them need connectivity with an external server to store the data, make them accessible, and synchronised on all user’s platforms and devices. It sounds reasonable to have just one backend for all of the platforms. It means that the app will give consistent user experience everywhere and also it is easier and cheaper to write just one version of code instead of creating and maintaining them separately.
Because most of the time in my career while starting to work on a mobile app I was cooperating with developers specialised in web development. I assume it is a very common situation. The questions, obstacles, and things that I had to explain to these developers were surprisingly identical. Because of this commonality, I decided to write this blog post and explain why and where are the differences and how to build API that will be constructed to work well with both mobile and web applications.
So what are these differences that we have to pay attention to?
1. Decrease number of requests
One of the most important things is to design applications to make as little requests per screen as possible. It is a good practice to return all necessary information after one request. Often when I was coming to backend developer and asking to merge several endpoints into one I always received an answer “Why don’t you make two requests? It’s not a problem”. Well, maybe on a website it is not really noticeable. Usually, when browsing a website on a computer you have better hardware than mobile and stable, faster internet connection. But imagine using the application while being on bus and internet connection is weak. If you make two requests instead of one. This means that the loading time is two times longer. Instead of loading 3 seconds, it will load 6. Research showed that this kind of delay already causes users frustration and may lead to bad reviews of the application.
As an example let’s imagine that we have a simple screen of application that displays the user’s list of notifications. On the top of the screen, we display information about how many unread notifications user have. Instead of having two separate endpoints for downloading list and top screen information, we can have one that returns all information at once and response looks like this:
In most cases, it is possible for the web to consume this optimised for the mobile endpoint. For the web, we can say it doesn’t change much but for mobile, it increases user experience (loading time) tremendously.
2. Heavy lifting done on the server side
You want to have your mobile app light and focused on fast and smooth presenting data to your user. That’s why all data operations and logical actions should be done on server side.
Besides that, if you allow any calculation to be done on the client’s side (like sorting, data wrangling, sensitive tasks) there starts to be a chance of inconsistency. It’s possible that on any platform (Android, iOS, web, etc.) logic will be implemented differently. Especially with time and when the application is evolving through many iterations.
3. Versioning
Web developers when releasing a new version they have full control of the environment and version of an application that users will see. With mobile development, you don’t have this degree of freedom. You don’t know when and if all the users will upgrade the app. You have no way to force users to update the application. This means that you can’t remove old endpoints or unused in new version fields in response objects. If you edit existing endpoints you always have to keep in mind to don’t break old versions of applications. Usually, no one thinks about this but it’s a good practice to include old versions of the app in your test case scenarios.
4. Pagination
To don’t wait too long for response and to don’t load too much information into working memory a good practice is to implement pagination. As there is a need you can request to load more data. This solution will benefit both mobile and web platforms.
5. Media files
If requested objects in response contain any media files it is defiantly better if the server puts only URL-s in the response. URL-s can be for example S3 addresses if you store data on AWS S3. Time for wait will be tremendously shorter. And all platforms have good libraries to handle images that will download media automatically, show loading placeholders, and cache data. It will look professionally without any efforts and give a better user experience.
6. Include device informations in request headers
It is a good practice to include information about the device and system version in request headers. If you have a lot of users or testers using application simultaneously it is very helpful. It helps while checking logs and trying to debug or figure out what happened. Also when live users are reporting some problems trough support you do not dispose of full information about their system and device which might be the key point to figure out source of the issue.
7. Meaningful error messages
The server should always return some meaningful error messages in a form that can be directly displayed in the app. Not just standard 400 and 500. First of all, if handling errors would be hardcoded in application code than to change this messages would mean that they will not change until the user update the app to the newest version. With the server version, there is no problem with that. User will have displayed whatever server returns. Second of all, a generic solution that can be used everywhere in the application is a much cleaner and elegant solution. And the last thing is that developer might not predict all possible errors occurring. Server-side will handle this better.
Summary
As you can see most of the advices focus on how to adjust server to have a better performance on mobile. Perhaps it might be a little bit because I am a mobile developer and pay more attention to this issues but also because mobile is much more fragile for any connectivity issues. Also users are less patient and giving bad reviews on App Store/Google Play when get frustrated. That can be deciding on application success in the future.
Usually, those changes don’t have meaning for the web or even improves loading speed. So it is definitely worth it. There are some big applications (like Facebook for example) that create separate APIs for mobile and web, but for more average size applications one API version for all platforms will be a way more elegant solution. Especially if we have to count and optimize the budget for building our product.