```html

Usage

The created REST support offers the following set of functionalities:

Authentication

Login

To allow the user to authenticate in the portal through an external application, a REST authentication call was provided at the following address.

{Base URL of the website}/lumis/api/rest/lumlogin

Calls to this endpoint must be made using the HTTP method POST.

Parameters:
This endpoint supports the following parameters:

username: Required parameter indicating the username (login) that will be authenticated in the portal.
password: Optional parameter indicating the user's password to be authenticated. This parameter is optional in the sense that the user's password can be a blank password.
locale: Optional parameter indicating the language in which the user will be authenticated. This parameter influences the current language of the user session created and, therefore, subsequent translations in the use of the portal.
mfaToken: Parameter that indicates the token used in authentication, if multi-factor authentication is enabled in the portal.

Return:
This method returns the following HTTP codes:

204: If the authentication was successful. In this case, the portal will add response cookies related to the user's session.
403: If the provided combination of username and password is not valid.
400: If the username was not provided in the request.
500: If an unexpected error occurred during the processing of the request.

The following example shows how to make a call using Jquery: $.post("http://myserver:8080/portal/lumis/api/rest/lumlogin", { "username": "myUser", "password": "my password" }) .fail(function(xHR, error) { /* some failure occurred */ }) .then(function() { /* at this point the user has already been authenticated */ }); In this example:

http://myserver:8080/portal: Is the base URL of the website.
/lumis/api/rest/lumlogin: Is the path of the REST method.
myUser: Is the login of the user to be authenticated.
my password: Is the password of the user to be authenticated.

Sending Multi-Factor Authentication Token Email

This call will send an email that contains the Token for user authentication in the portal, if multi-factor authentication is enabled.

POST {protocol}://{domain}[:port]/lumis/api/rest/lumis/authentication/sendMFATokenEmail/[userLogin]

Example:

http://<my domain>/lumis/api/rest/lumis/authentication/sendMFATokenEmail/myUser

Return:
This method returns the following HTTP codes:

204: If the email sending to the user is successful.
409: If the portal does not have multi-factor authentication enabled.
404: If the provided user login does not belong to a registered user in the portal.

Logout

This call should end the user's session in the portal.

{protocol}://{domain}[:port]/lumis/api/rest/lumlogout

Current User.

In order to obtain the data of the currently logged-in user in the system, the following Rest call can be made:

{protocol}://{domain}[:port]/lumis/api/rest/lumis/authentication/users/current

This, in turn, returns a JSON containing the public data of the user. For example, the logged-in user will be "admin":

Locale Change

A call capable of changing the language of the current session (guest or authenticated) has been created. The basic format is shown below.

{protocol}://{domain}[:port]/lumis/api/rest/lumsetlocale/[locale]

Examples:

http://<my domain>/lumis/api/rest/lumsetlocale/pt_BR
http://<my domain>/lumis/api/rest/lumsetlocale/en_US

If the mentioned ‘locale’ is not supported by the portal, the current language will be maintained.

If the parameter is not specified, the portal will revert to the default ‘locale’.

Reading REST Interface

A call has been created capable of querying the information contained in the sources defined in the REST interfaces. The basic format is shown below.

{protocol}://{domain}[:port]/lumis/api/rest/{rest-name}/lumgetdata/{restinterface-name}[.returnType][parameters]

Protocol: connections via http and https are accepted.
Domain/port: domain and connection port of the website.
rest-name: REST name of the service instance.
restinterface-name: name of the REST interface of the service used.
Return type: can receive values ‘json’ or ‘xml’, indicating how the information will be returned (JSON or XML, respectively – default ‘json’).

Examples:

http://<my domain>/lumis/api/rest/news/lumgetdata/list
http://<my domain>/lumis/api/rest/news/lumgetdata/list.json

The parameters may include:

Maximum number of items (lumMaxRows)
This parameter is optional and is used as in the following example, which brings the first five news published in the service instance called ‘news’.

http://<my domain>/lumis/api/rest/news/lumgetdata/list.json?lumMaxRows=5
First item in the list (lumStartAt)
This parameter is optional and is used as in the following example, which brings the second page of news published in the service instance called ‘news’, considering five news per page.

http://<my domain>/lumis/api/rest/news/lumgetdata/list.json?lumMaxRows=5&lumStartAt=6
Sorting (lumOrderBy)
This parameter is optional and is used to define a sorting by a specific field in ascending or descending order (ASC or DESC respectively).

The following example sorts the acquired news by their title, in ascending order.

http://<my domain>/lumis/api/rest/news/lumgetdata/list.json?lumMaxRows=5&lumStartAt=6&lumOrderBy=Title ASC
Returned fields (lumReturnFields)
This parameter defines which fields should be returned. By default, when this parameter is not informed, all fields explicitly defined in the source of the REST interface will be returned along with the fields "Primary key of the source" and the "Content Identifier" (if it is a content service). When this parameter is informed, the fields that will be returned will be those defined in the list of fields that must be separated by commas (",").
If you wish to return all fields simply inform "*" as the value of the lumReturnFields parameter.

The following example returns the key fields and content identifier along with the explicit fields of the REST interface.

http://<my domain>/lumis/api/rest/news/lumgetdata/list.json

The following example returns the fields description and who created the content.

http://<my domain>/lumis/api/rest/news/lumgetdata/list.json?lumReturnFields=createdBy,description

The following example returns all fields of the source.

http://<my domain>/lumis/api/rest/news/lumgetdata/list.json?lumReturnFields=*

Obtaining content via its slug

The LumisXP has a feature to obtain content via its slug. For this, the following requirements must be met:

The service must have a REST details interface that includes a filter of the content identifier read from the request parameter lumItemId.
The service instance where the content was registered must have the REST support enabled.
The content must have been registered with a slug.

Example:
Suppose the service has a REST interface called details that receives the identifier of the content in the parameter lumItemId and that the instance of this service has REST support enabled and has a REST name my-instance, a content with identifier EF179CC52E8444B88FC1CEDAF2E21939 could have its details accessed through the URL http://myserver/lumis/api/rest/my-instance/lumgetdata/details?lumItemId=EF179CC52E8444B88FC1CEDAF2E21939.
Now, if the content belongs to a source with identifier default and has a slug my-content, this same content could also be accessed through the URL http://myserver/lumis/api/rest/my-instance/lumgetdata/details/default/my-content.

This feature is especially important when LumisXP is used as a headless CMS.

Process Action Call API

A call capable of executing a given process action has been created. This call is intended to be typically used from the browser, but is not limited to it. There are two basic formats shown below.

POST {protocol}://{domain}[:port]{application-context}/lumis/api/rest/{rest-name}/lumPA/{interfacesimple-id}.json POST {protocol}://{domain}[:port]{application-context}/lumis/api/rest/{rest-name}/lumPA/{interfacesimple-id}/{lumaction-id}.json

protocol: connections via http and https are accepted.
domain / port: domain and connection port of the website.
application-context: context in which the application is executed or an empty string if the application is executed at the root. For example: /portal.
rest-name: REST name of the service instance.
interfacesimple-id: simple identifier of the interface. It is the part after the last . of the interface identifier. For example, in the interface lumis.service.news.add it would be add.
lumaction-id: identifier of the process action. Example: commit.

Examples:

http://<my domain>/lumis/api/rest/news/lumPA/add.json
http://<my domain>/lumis/api/rest/news/lumPA/add/commit.json

Help of Process Action Call API

A call has been created that can query the controls of the requested interface and return the definitions of the request parameters as a response. The basic format is shown below.

GET {protocol}://{domain}[:port]{application-context}/lumis/api/rest/{rest-name}/lumPA/{interfacesimple-id}/help

protocol: connections via http and https are accepted.
domain / port: domain and connection port of the website.
application-context: context in which the application is executed or an empty string if the application is executed at the root. For example: /portal.
rest-name: REST name of the service instance.
interfacesimple-id: simple identifier of the interface. It is the part after the last . of the interface identifier. For example, in the interface lumis.service.news.add it would be add.

Example:

http://<my domain>/lumis/api/rest/news/lumPA/add/help

Check if user is a group member

Checks if the logged-in user is a member of a given group. Responds with a json of an object with a 'result' boolean property that indicates whether or not they are a member.

GET {protocol}://{domain}[:port]{application-context}/lumis/api/rest/lumis/authentication/users/current/isMemberOf/{groupAlias}

protocol: is the access protocol to the portal (normally, http or https).
domain / port: domain and connection port of the website, where the port may be omitted if it is default. Examples: mywebsite.com:8080, mywebsite.com.br etc.
application-context: context in which the application is executed or an empty string if the application is executed at the root. For example: /portal.
groupAlias: The alias of the group to which the check will be made. Example: admins, registered etc.

Example of response body

Usage Example

Get user geolocation information

Obtains information about the user's geolocation. This information is based on the user's IP address, and thus may not have precision or even be available, but generally provides a good result with city-level granularity. This is an alternative to using the JavaScript geolocation API, which requires user permission and availability on the device in use to function.

GET {protocol}://{domain}[:port]{website-path}/lumis/api/rest/lumis/geolocation/currentPosition

protocol: is the access protocol to the portal (normally, http or https).
domain / port: domain and connection port of the website, where the port may be omitted if it is default. Examples: mywebsite.com:8080, mywebsite.com.br etc.
website-path: is the path of the website as registered. Can be an empty string if the URL of the website is at the root. For example: /portal.

Example of response body

If it was not possible to identify the user's geolocation, the response body will be an empty object {}.

Usage Example

Troubleshooting

For possible solutions to problems, see this page.

```