Page tree
Skip to end of metadata
Go to start of metadata

This page describes how you can request localized content with the Delivery endpoint API.

In Magnolia REST 2.1.x, version 2 of the delivery endpoint allows you to send an API request for a specific language variant of content. This is different from the previous implementation (REST 2.0.x), in which the endpoint version 1 always delivered all language variants available in the JCR repository. 

Specifying the language

With endpoint v2, you can request a single language variant, or send lang=all in the request to return all language variants available.

To request a specific single language variant, do one of the following:

  • Set the Accept-Language header. For example:  Accept-Language: de-DE
  • Set the langquery parameter. For example: lang=de-DE

If both are set, the lang parameter takes priority. If neither is set, the decision is delegated to the I18nContentSupport interface.

To return all language variants:

  • Set the lang query parameter to all: lang=all

You can use both the Accept-Language header and the lang query parameter for both sub-resources Read node and Query nodes.

Examples

The example requests below make use of the title and title_de properties of the /travel/about page in the Travel Demo.

The reponses are returned based on the following configuration:

6.1.3 release

rm  includeSystemProperties: false in the config below

/<my-module>/restEndpoints/ep.yaml
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
rootPath: /
nodeTypes:
  - mgnl:page
includeSystemProperties: false

Neither parameter

If neither the header or the lang query parameters is used in the request, the language used for the response refelcts the locale determined by the the I18nContentSupport interface.

Accept-Language header

Request URL

JSON response

not set

/.rest/ep/travel/about

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "About",
 "@nodes": []
}

The language is not defined by the header or the lang parameter. The value returned for title is determined by the I18nContentSupport interface.

Both parameters

If both the header and the lang query parameters are set. The query parameter takes priority.

  • The parameter is parsed for a single language tag.
  • If the tag is a full language tag such as de-CH or en-US, and the system does not have a perfectly matching counterpart, the system selects the closest variant (deen). See the getNextLocale method of AbstractI18nContentSupport.
  • If lang=all is set all language variants are returned.
Accept-Language header

Request URL

JSON response

Accept-Language: en-GB

/.rest/ep/travel/about?lang=de-DE

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "Über uns",
 "@nodes": []
}

Both the header and the lang parameters are set, the lang parameter takes priority for content delivery.

Accept-Language: en-GB

/.rest/ep/travel/about?lang=all

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "About",
 "title_de": "Über uns",
 "@nodes": []
}

All language variants are returned since lang=all was sent in the request.

Only the header

If only the Accept-Language header is set.

  • Server-driven content negotiation algorithms select the best match for the language tag set in the header.
  • If the value is * (wildcard), it means that any language the server may return is acceptable.
  • The value can be in the form of weighted syntax, for example Accept-Language: fr-CH, fr;q=0.9, en;q=0.8.
Accept-Language header

Request URL

JSON response

Accept-Language: de-DE

/.rest/ep/travel/about

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "Über uns",
 "@nodes": []
}

Server-driven content negotiation is used to select the best match for the language tag specified in the header.

Only the lang parameter

If only the lang query parameter is set.

  • The parameter is parsed for a single language tag.
  • If the tag is a full language tag such as de-CH or en-US, and the system doesn't have any perfectly matching counterpart, the system selects the closest variant (de, en). See the getNextLocale method of AbstractI18nContentSupport.
  • If lang=all is set all language variants are returned.
Accept-Language header

Request URL

JSON response

Not set

/.rest/ep/travel/about?lang=de-DE

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "Über uns",
 "@nodes": []
}

Selects the closest supported locale to that specified by the lang parameter.

Not set

/.rest/ep/travel/about?lang=es-ES

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "About",
 "@nodes": []
}

Responds with a fallback value since the title_es property, which could hold a Spanish translation, is not defined for the page and/or the es locale is not configured for the site.

See also