Frontend - Backend Interaction

CXBox provides a standardized and unified API mechanism for frontend–backend communication. Developers don’t need to design or maintain custom APIs — all data operations (read, update, delete, metadata retrieval, and custom actions) are handled by built-in endpoints. This approach simplifies development, improves consistency, and reduces integration errors.

The platform includes a universal interaction mechanism that works equally well for forms, tables, and other widgets. This means that when you change the widget type, the underlying logic remains correct - everything continues to function without requiring additional API configuration.

In this article, we'll examine how this mechanism is structured and explore the fundamental API methods that make it work.

This page provides an understanding of the correspondence between UI elements and REST calls.

A backend call can be routed to either any source or version and is processed as follows:

• VersionAwareResponseService
• AnySourceVersionAwareResponseService

API Structure

Interaction between the frontend and backend in CXBox is built on four types of APIs:

• /data
• /row-meta/
• /custom-action
• /count

The API is structured as follows:

• independent entities: .../screen/bc or .../screen/bc/id
• for dependent parent-child relationships: .../screen/parent_bc/id/child_bc or screen/parent_bc/id/child_bc/id

Example:

/data

/row-meta

Metadata describes which fields are enabled, which buttons are visible, and so on.

/custom-action

/count

CXBOX Core Principle

All widgets work under the same logic.(except for FormPopup) This ensures that switching from one widget type to another does not disrupt the API functionality.

Examples

Data Loading: independent BCs

Let’s consider a screen with a single List widget.

1. Open the Developer Tools → Network tab.
2. Load the screen containing the list.

We can see that three API calls are executed.

sequenceDiagram
    Frontend->>Backend: GET /api/v1/data/screen/bc
    Frontend->>Backend: GET /api/v1/row-meta/screen/bc/id
    Frontend->>Backend: GET /api/v1/count/screen/bc

GET /api/v1/data

How does it look?

Description

This request retrieves the data to be displayed on the screen. It respects pagination parameters (page, limit), as well as filtering and sorting conditions.

The diagram above shows how the API response directly maps to the UI elements displayed in the list.

GET /api/v1/row-meta

How does it look?

Description When the list screen opens, CXBox automatically places the cursor on the first record — you can see this as the highlighted first row.

The metadata response defines the state of the user interface controls, such as active buttons and editable fields, for the first record.

(This call is made for only a single record to ensure proper operation in accordance with the CXBox Core Principle. We fetch metadata for a single record rather than all records for performance reasons. Parent-child relationships often involve complex logic, and calculating metadata for a large number of records could lead to slow UI response times.)

The diagram illustrates how fields correspond to their properties received from the backend.

• When the backend sends a field state with the parameter disabled: true, the frontend displays the field as read-only (not editable).
• When the parameter is disabled: false, the frontend displays the field as editable.

This principle applies to all properties provided by this API — each property received from the backend directly determines how the field is displayed and behaves on the client side.

GET /api/v1/count

How does it look?

Description

The count method returns the total number of records. The call depends on the Pagination parameter — see Pagination. The frontend uses this value to display information about the total number of available records.

For example: “Showing 5 out of 10 records.”

Data Loading: dependent parent-child BCs

Let’s consider a screen with a single List widget.

1. Open the Developer Tools → Network tab.
2. Load the screen containing parent–child BCs.

When the screen loads, you can see that several API calls are executed:

sequenceDiagram
    Frontend->>Backend: GET /api/v1/data/screen/parent_bc
    Frontend->>Backend: GET /api/v1/row-meta/screen/parent_bc/parent_bc_id
    Frontend->>Backend: GET /api/v1/count/screen/parent_bc
    Frontend->>Backend: GET /api/v1/data/screen/parent_bc/parent_bc_id/child_bc
    Frontend->>Backend: GET /api/v1/row-meta/screen/parent_bc/parent_bc_id/child_bc/child_bc_id
    Frontend->>Backend: GET /api/v1/count/screen/parent_bc/parent_bc_id/child_bc

Parent Widget

For the parent widget, everything described above applies — standard data, row-meta, and count requests are executed.

Child Widget

For the child widget, everything works the same way, except for the following differences:

• The requests include parent/child prefixes, reflecting the BC hierarchy.
• Data for the child entity is calculated only for the first automatically selected record.

General Principles

For all widget types, the system always performs API requests (/data, /row-meta, /count), including fields that use popup widgets.

Exceptions: FormPopup, notifications, filePreview, and customization of displayed columns calls — these behave differently.

GET /api/v1/data

How does it look?

Description see description

GET /api/v1/row-meta

How does it look?

Description

see description

GET /api/v1/count

How does it look?

Description see description

Edit (Force Active)

When editing data, any changes are not sent to the backend until the user clicks the “Save” button. However, some fields can be marked as force-active. For such fields, every time their value changes, a request is automatically sent to the backend, and the updated values of dependent fields are returned to the frontend. This is useful when the value of one field depends on another.

sequenceDiagram
    Frontend->>Backend: POST /api/v1/row-meta/screen/bc/id

POST /api/v1/row-meta

How does it look?

Description

Let’s look at an example where the country field is marked as force-active. When the user changes the value of this field, the region and street fields should be automatically updated.

1. All fields are initially empty

1. Fill in the "Country" field The user selects a value in the Country field. After the value is selected, a meta request (/api/v1/row-meta) is triggered.

1. Dependent fields are updated On the backend, the region and street fields are automatically filled based on the selected country, and the updated values are returned to the frontend.

FormPopup

All widget types follow the described logic above Independent BCs,dependent parent-child BCs, except for FormPopup.

The reason for this exception is that when a FormPopup is opened, it doesn’t just display existing data — it triggers a process similar to changing the active field and then updating its dependent fields.

This means that when the popup is opened, we must fetch the latest row meta to ensure that recalculated and up-to-date fields are displayed. Like ForceActive but with button.

sequenceDiagram
    Frontend->>Backend: POST /api/v1/row-meta/screen/bc/id

POST /api/v1/row-meta

How does it look?

Description

see description

Standart action

Save

sequenceDiagram 
    Frontend->>Backend: PUT /api/v1/data/screen/bc/id
    Frontend->>Backend: GET /api/v1/row-meta/screen/bc/id 

PUT /api/v1/data

How does it look?

Description

see description

POST /api/v1/row-meta

How does it look?

Description

see description

Custom-action

Clicking the custom button triggers 3 calls:

sequenceDiagram
    Frontend->>Backend: GET /api/v1/custom-action
    Frontend->>Backend: GET /api/v1/data
    Frontend->>Backend: GET /api/v1/row-meta

GET /api/v1/custom-action

How does it look?

GET /api/v1/data

How does it look?

Description see description

GET /api/v1/row-meta

How does it look?

Description

see description