Pitfalls when developing a mobile application using Bitrix REST API
My name is Andrey Buinovsky, I am a developer at an IT company. My team and I decided to write this article and share some problems, pitfalls and their solutions in developing a mobile application for one of our retail customers.
We have developed an online store for a large retail chain. After launching the online store, we moved on to developing the project, which included the task of creating an additional channel for interacting with customers. There was no question about choosing an API for the backend, since the online store was developed on the 1C-Bitrix platform, the system has the necessary functionality to work with an alternative front and mobile application. Our team was faced with the task of developing a mobile application based on the Bitrix REST API for the iOS and Android platforms while maintaining the functionality of the customer’s existing online store. This meant using components already implemented for the online store, copying them to preserve the logic, removing the layout, and using the returned data.
During development, we encountered the following problems, some of which we created for ourselves:
strict data typing on iOS and Android mobile platforms,
distribution of models for their maximum reuse,
did not divide the data into several methods (affects loading speed),
extra data in the method that can be obtained by event,
did not use skeleton,
when there was a large amount of data, the component was not cached,
did not use session splitting and non-blocking sessions when using memcached.
Our development team was given a task: all functionality implemented in the online store should be available in the mobile application. To do this, we used the fact.api module (developed in our company), using its technical methods, for example, to generate and validate tokens. However, for all aspects related to receiving and transmitting data, we had to develop our own methods.
We took components of an online store, inserted them into methods and obtained data from them using ob_start(); $str = ob_get_contents(); ob_end_clean();
But initially, during development, we did not take into account the issue of correctly naming keys in arrays and creating common models for the same type of information in different places in the application; we did it as if for “NUXT”. After connecting mobile developers, we realized that we had problems with data typing, because they received a string or int in the same field, which caused the mobile application to crash.
When we started typing the data in result_modifier.php, and everything seemed to be working out, we encountered the following problem: json_encode and json_decode after conversion changes the data type itself, for example, we pass id as string, and get int as output. To prevent this from happening, you need to make sure that there is no key in json_encode JSON_NUMERIC_CHECK. Then the data type will not change during decoding.
The next problem was that if the keys in the array are associative (not 0,1,2), then the data type will be an object, and when the array is empty, then it is worth typing it into an object so that the application does not break.
You should distribute repeating blocks in the online store as much as possible and write models for them, and then reuse them everywhere so that the names of the keys and data types are the same and, if corrected in one place, they will not be broken in another.
It is worth using the SOLID principle, that is, when returning data, distribute it as much as possible into as many methods as possible, because a mobile application can receive them asynchronously, and then the application will work faster. For example, there may be a huge amount of data for the main page of an application, but the user will see only 25% at once, and the rest can be loaded later.
It is necessary to use a skeleton so that the layout skeleton is displayed in the application, and as data is received, it is filled in. It looks more visually pleasing and there will be no layout jumps.
You should not overload the json method with unnecessary data. The data that is not needed for output, but the component provides it, should be cut out, thereby reducing the size of the page returned by the server.
While debugging the application, we noticed that some requests took a very long time to process, but there were no labor-intensive processes there. When delving into the problem, we realized that we were blocking requests and they were lining up in a queue. We solved this problem by dividing the sessions into a non-blocking one. If we are sure that our request will not make any changes, but is only needed to receive data, then we set the parameter there define('BX_SECURITY_SESSION_READONLY', true);, and the request is not blocked.
For debugging, it is worth making it possible for users (testers, customers) to select the server to which requests will be sent. This is necessary so that when using the release approach, when each task is accepted on a separate review site, it is possible to accept different tasks or compare devs with production without reinstalling the application.
Additionally, it is necessary to implement a logging mechanism on the side of the mobile application during the development process, since such logs are often important. For example, it is required to register information about data received from the server, as well as data sent from the mobile application to the server, in logs on the side of the mobile application.
General recommendations for the mobile application:
If you, as a development team, receive the requirement “to make a copy of the online store in MP,” then you need to record differences in processes or functionality in the technical specifications.
It is recommended to include in the Technical Specifications (hereinafter referred to as TK):
describe the functionality of the functionality in as much detail as possible – to eliminate disagreements during development by two different teams of Android and iOS.
description of the process “What will happen in MP when a user is deleted/blocked/deactivated.” One possible solution is to transfer the user to the authorization screen in case of an error.
description of business processes for Push notifications for orders – which notifications will be used when order status and payment change.
handling validation errors on each screen. Errors with invalid data should not lead to the crash of the mobile application or the screens in it (you need to specify optional types in the response model from the back, that is, with the ability to set them to null, and then simply assign them default values. In the case when this data is critical for the application to work – throw an exception, but handle it by showing a dialog, like, something went wrong, but not crash the application).
When a developer writes an api in postman, it is necessary to describe business processes in it – a list of requests one after another with the result, so that MP developers can see how, what and why to call + attach example responses with descriptions, this will allow other developers to use the API correctly and not have to think about it Nothing.
Describe mandatory/optional parameters in requests/responses + data types.
Take into account the development of screen styles for MP, so as not to draw all screen options in the design.
To support versioning, provide the transfer of the version-api parameter from the application to the API – for functionality that should not work without updating the MP, as well as the user-agent parameter – for functionality that should differ depending on the platform (Android or iOS).
Initially, implement an update in MP for XYZ versions, so that future users will not have problems with mandatory updates. The naming of versions follows the pattern xyz, where:
x – backwards incompatible API changes made;
y – new functionality has been added that does not violate backward compatibility;
z – backwards compatible changes.
For debugging, make it possible to specify url requests (server url) in MP. This will make it possible to quickly switch the mobile application build between the pre and prod server for testing.
MP requires request/response logs in the debug version. Storing logs in MP.
Create a description of how headers work in requests – about phpsessid, geolocation, etc.
It is advisable to make requests in the background so that the user can work in the application, and the rest of the information will be loaded.
If memcache is used, then we use split sessions and a non-blocking session.
For pages with filters, clear query parameters are needed so that there is one cache on different platforms. You need to list these options in a common summary list for both platforms (Android and iOS).
Recommendations at the MP support stage:
– be sure to evaluate new modifications to tasks taking into account old and new versions of applications, so that it does not break on the old ones and works on the new ones.
create different review platforms at pre-sale to separate MP tasks. This will speed up the delivery of tasks to the customer and reduce the number of bugs during acceptance.
think over the functionality for painless authorization in MP under any user for debugging and testing.
Conceptually, the application is designed for “one user – one device.” If the user first logged in on one device and then logged into his account on the second, then push notifications will only arrive on the device on which the user was last logged in.
I am sure everyone found something interesting or useful for themselves in this article. I invite you to discuss and develop the topic in the comments. What did you encounter when developing a mobile application using the Bitrix REST API?
Authors: Buynovsky Andrey, Illarionov Anton.
Edited by Anastasia Danilchenko and Yulia Krainya.
