Requesting localized content with the delivery endpoint

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:

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.

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

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 (de, en). See the getNextLocale method of AbstractI18nContentSupport.
• If lang=all is set all language variants are returned.

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

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

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.

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

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.

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

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

See also

• RFC 5646 – Tags for Identifying Languages
• IANA's Language subtag registry