Documentation

New CRM API

Criteria and objectives

During the SPA development process, a corresponding objective was established to wrap it into a general API, which can provide for a convenient handling of not only SPA items, but also elements of any types of entities.

The following criteria were used when designing new API:

  • Reduced code duplication.
  • Loosened class cohesion.
  • Implemented test coverage.

Main objectives were set as follows:

  • Increased code quality.
  • Reduced number of errors.
  • Increased development speed and implementation of new features.

To improve structure of the code, it was decided to split it into services.


Service - is an object, usually, in singular instance, that execute a small-scale dedicated portion of logic.

Services must strictly adhere to the shared responsibility mode. This requires a significant number of them.

Service instances are retrieved via Service\Container.

Categories

In addition to services, significant amount of auxiliary code was written. Complete code can be separated into several categories:

Access point when handling new API is Service\Container.

It produces a required service, with required methods called.

In case of software logic is attached to any specific entity type, access point is Service\Factory.

Concepts

Below are some basic concepts that must be considered when handling this API.


Developer Experience

Positive Developer Experience was one of focal points during the development.

Set objective was to reduce difficulties with feature introduction and understanding of why one or the other method is being called.

Below are some of specifics applicable to the complete code.


Naming rules

Bitrix24 development team implemented the following naming rules for the new API:

  • Base class is located in a "general" namespace. For example, \Bitrix\Crm\Service\Operation.
  • Its descendants are located in the folder with the same name, as the base class. For example, \Bitrix\Crm\Service\Operation\Add.
  • When using the base class implementation, parent namespace is required to be included into the code. For example,
    use Bitrix\Crm\Service\Operation;
    
    $addOperation = new Operation\Add();
    

Services

CRM concentrates a lot of features. To reduce cohesion between classes, majority of features was split into services.

Each service solves a specific task or a job. Amount of services is significant, which allows easy handling.


Dedicated business logic

During API design stage, large focus was devoted to layering of classes into three base classes.

  • Date.
  • Business logic.
  • Interfaces.

Classes and methods for handling business logic shall not upload the data. Data must be received in a finalized format, significantly simplifying the process of test coverage.


Unit tests

Class design must envisage testing, thus improving class structure. Availability of tests in itself, speaks to the improved code quality.

Bitrix24 introduced a significant amount of tests for new classes (as well as for some old ones).


Error processing

Majority of methods that execute any updates are returned by the object Bitrix\Main\Result or its descendants.

This allows to correctly process/show operational errors.



© «Bitrix24», 2001-2022
Up