Cubes APIs

Definition of a cube

With a view to providing a better adapted way to accessing data, we have created an API that enables you to request the data represented by a cube. A Cube is a three-dimensional representation of data such as:

• Dimension axis: Data identifier.

• Raw values axis: Flat projection of the data.

• Measure axis: A projection of data in relation to a sub-set expressed according to an aggregator.

A cube is identified via its Id. For example: Analysis.Users takes a user as a starting point and enables us to list users per establishment via a dimension Establishment.Name. Another cube Analysis.Establishments takes an establishment as a starting point, and enables you to list users with the dimension Member.Name and show the number using the measure Member.Id with the aggregator Count.

Definition of a criteria

To reduce data volumes, we can use filters that we call criteria. A criteria has three elements:

• Field: a target dimension.

• Comparator: Set the comparison to apply to the value.

• Value: the value of the comparison.

Example: a criteria { Field: « User.FirstName », Coperator: Equal, Value: “Paul” } will restrict results to users called Paul. These criteria can be regrouped in an operator object that defines the operation AND or OR to apply to any child objects.

Note: the root element operates an AND on its children.

Exploit existing reports

Within Xperience, you can interrogate these cubes using the reports in the Analyse module. To create a report, you need to start by selecting a cube before defining Dimensions and Measures (Values).

When creating a report you can also retrieve the API request that corresponds to the report you have just created:

Note: This feature is also accessible via an API request.

GET /api/cubes/customreports

GET /api/cubes/customreports/{REPORT_ID}

Why use the cube API?

Reports are systematically displayed with a short pagination. However, insofar as the cube API is implemented as a Backend-to-Backend requirement, pagination is only applied on request and according to the volume of data requested. This can result in extended processing times.

In order to overcome the response time limitation of the http protocol, we have unlinked the request from its response. Whereas a standard REST API such as OData's returns the data as the content of the response, the cube API returns a GenerationID processing.

This GenerationID will retrieve the result once the generation is complete. There are significant advantages to this procedure. The most pertinent being that, once the result is available, it can be retrieved several times with a relatively low impact on the database.

We can schedule a task that will run within a given time slot and return the result when required to avoid impacting the database at certain times.

Online technical documentation

The Cube API exposes a certain number of potential requests. They are described in the online documentation accessible here —> https://server-xperience.syfadis.com/swagger/ui/index:

You need to be connected to Xperience to access this page.

The use of the cube API is dependent on Basic-Auth authentification via an oData user for which we can define a language. Data is generated to the language of this user.

Build a request

The first step is to define the cube that will serve as a starting point. Use this request:

GET /api/cubes

Once the cube is defined, you can add any dimensions and measures (values) you wish to return.

Use these requests:

GET /api/cubes/{CUBE_ID}/dimensions  

GET /api/cubes/{CUBE_ID}/measures

In our example, there is a complexity weighting = 1, meaning that the data is in the root cube. If this value increases, it means that data is found in the nested cubes.

Note that the Gender dimension type is Enumeration.

You will find corresponding values with the request:

GET /api/cubes/{CUBE_ID}/criteria/{field}

We can create a simple yet exhaustive request:

These 2 screens represent the same report designed from the reporting tool where the API request is retrieved. This request can be retrieved from the Copy the API request button in the Report tab. The presence of this button is conditional on a configured privilege.

We uses the cube Analysis.Users, targetting 2 dimensions and a Count value. There is no page size configurations.

Generate the cube

When you have collected all the elements, we can move on to the second step: request a generation.

This occurs via the POST /api/cubes request. Here is a simple but exhaustive example:

Follow progression

The API retrieves the GenerationID with which we can follow the data generation progression with the request:

GET /api/cubes/status

Note: You can make this request during the generation process; the Status Code will be adapted to the level of progression.

If the result of this example shows a low volume of data, the JSON file that is generated can comprise a much larger file that is stored on the server.

It is useful to regularly purge data from temporary, a retention period of 14 days is set.

Data can also be manually deleted (before this retention period) using this route:

DELETE /api/cubes/{GENERATION_ID}

Scope and language applied to the use of APIs

Unlike reports in analyses, no default visibility filter is applied when using the cube API.

For multilingual properties, data is retrieved in the language of the connected OData user.

Conclusion and endpoint examples

Three main endpoint typess can be easily tested with a PostMan client:

• POST : https://{server-xperience}/api/cubes

  • Where the cube specifies in the body, the projected dimensions, possible measurements and criteria.

  • To constitute this body, use the Copy the API request button.

  • A processing ID is returned.

• GET : https://{server-xperience}/api/cubes/status

  • Allows you to view report generation status (processing Ids): treatment start/end date, file size generated, status.

    Reports are generated in a temporary directory which is automatically purged every 15 days to avoid unnecessary disk space overload.

• GET : https://{server-xperience}/api/cubes/result/{idTraitement}

  • Provides JSON data associated with the processing ID.

Additional endpoints are available to list the available cubes, their dimensions and measurements, for example.

• GET : https://{server-xperience}/api/cubes/customReports

• GET: https://{server-xperience}/api/cubes/customReports/{reportId}

  • Allows you to retrieve the JSON structure (to build your body) of all your reports, or of a specific one.

• GET : https://{server-xperience}/api/cubes/

  • Lists all usable cubes: name + description.

• GET : https://{server-xperience}/api/cubes/{cubeId}/dimensions

  • Lists all cube dimensions, in other words, retrievable properties.

• GET : https://{server-xperience}/api/cubes/Analysis.UserSkills/dimensions

  • Retrieves all dimensions from the user skills cube.

• GET : https://{server-xperience}/api/cubes/{cubeId}/measures

  • Does the same thing for the measures (values).