Messages API

When interacting with a frontend or mobile application, it is often needed to display localized messages of the application. As those translated values are already defined in the Jmix .messages files, the Messages API provides the ability to expose those values to the client application.

The Messages API provides the following two endpoints:

The Messages API by default uses the locale setting of the user obtaining the authorization token and returns the translated values accordingly.

Entity Translations

The Entity Translations endpoint allows retrieving information about the entity name, and the translated entity attribute names.

/messages/entities

Translation for the entity name and attributes of all entities.

/messages/entities/:entityName

Translation for the entity name and attributes of the given entity.

In the following example, you can see how to request translated values for the Order entity through the API:

Messages for Order Entity Request
GET http://localhost:8080/rest
            /messages
            /entities
            /rstex11_Order
Response: 200 - OK
{
  "rstex11_Order": "Order",
  "rstex11_Order.amount": "Amount",
  "rstex11_Order.createdBy": "Created by",
  "rstex11_Order.createdDate": "Created date",
  "rstex11_Order.customer": "Customer",
  "rstex11_Order.date": "Date",
  "rstex11_Order.deletedBy": "Deleted by",
  "rstex11_Order.deletedDate": "Deleted date",
  "rstex11_Order.id": "Id",
  "rstex11_Order.lastModifiedBy": "Last modified by",
  "rstex11_Order.lastModifiedDate": "Last modified date",
  "rstex11_Order.lines": "Lines",
  "rstex11_Order.version": "Version"
}

Enum Translations

The Enum Translations endpoint allows retrieving information about the enum name, and the translated enum values.

/messages/enums

Translation for the enum name and values of all enums.

/messages/enums/:enumClassName

Translation for the enum name and values of the given enum.

The parameter enumClassName is the full qualified name of the enum including the package name. So use rest.sample.entity.CustomerType instead of just CustomerType.

In the following example, you can see how to request translated values for the CustomerType enum through the API:

Messages for CustomerType Request
GET http://localhost:8080/rest
            /messages
            /enums
            /rest.sample.entity.CustomerType
Response: 200 - OK
{
  "rest.sample.entity.CustomerType": "CustomerType",
  "rest.sample.entity.CustomerType.BUSINESS": "Business",
  "rest.sample.entity.CustomerType.PRIVATE": "Private"
}

Request Specific Languages

It is also possible to explicitly request translated messages for a given locale by setting the Accept-Language header. In the following example, you can see how to request German translations for the CustomerType enum:

Language-specific Request
GET http://localhost:8080/rest
            /messages
            /enums
            /rest.sample.entity.CustomerType
Accept-Language: de
Response: 200 - OK
{
  "rest.sample.entity.CustomerType": "Kundentyp",
  "rest.sample.entity.CustomerType.BUSINESS": "Geschäftskunde",
  "rest.sample.entity.CustomerType.PRIVATE": "Privatkunde"
}