Open the menu

    Utilização

    O suporte REST criado oferece o seguinte conjunto de funcionalidades:

     

    Autenticação

    Login

    Para permitir que o usuário se autentique no portal por uma aplicação externa, foi provida uma chamada de autenticação REST, no endereço a seguir.

    {URL base do website}/lumis/api/rest/lumlogin

    As chamadas para esse endpoint devem ser feitas usando o método HTTP POST.

    Parametrização:
    Esse endpoint suporta os seguintes parâmetros:

    username
    Parâmetro obrigatório que indica o nome de usuário (login) que será autenticado no portal.
    password
    Parâmetro opcional que indica a senha do usuário a ser autenticado. Esse parâmetro é opcional no sentido que a senha do usuário pode ser uma senha em branco.
    locale
    Parâmetro opcional que indica em qual idioma que o usuário será autenticado. Esse parâmetro influencia o idioma corrente da sessão do usuário criada e, dessa forma, posteriores traduções na utilização do portal.

    Retorno:
    Esse método retorna os seguintes códigos HTTP:

    204
    Caso a autenticação tenha sido bem sucedida. Nesse caso, o portal irá adicionar à resposta cookies relativos à sessão do usuário.
    403
    Caso a combinação fornecida de usuário e senha não seja válida.
    400
    Caso o usuário não tenha sido fornecido na requisição.
    500
    Caso algum erro inesperado tenha acontecido durante o processamento da requisição.

    O seguinte exemplo mostra como realizar uma chamada utilizando Jquery: Nesse exemplo:

    http://meuservidor:8080/portal
    É a URL base do website.
    /lumis/api/rest/lumlogin
    É o caminho do método REST.
    meuUser
    É o login do usuário a ser autenticado.
    minha senha
    É a senha do usuário a ser autenticado.

     

    Logout

    Esta chamada deve encerrar a sessão do usuário no portal.

    {protocolo}://{domínio}[:porta]/lumis/api/rest/lumlogout

     

    Usuário Atual.

    Afim de obter os dados do usuário atualmente logado no sistema, pode ser feita a seguinte chamada Rest:

    {protocolo}://{domínio}[:porta]/lumis/api/rest/lumis/authentication/users/current

    Esta, por sua vez, retorna um JSON contendo os dados públicos do usuário. Como exemplo, o usuário logado será o "admin" :

     

    Mudança de Locale

    Foi criada uma chamada capaz de alterar o idioma da sessão atual (guest ou autenticada). O formato básico é mostrado a seguir.

    {protocolo}://{domínio}[:porta]/lumis/api/rest/lumsetlocale/[locale]

    Exemplos:

    • http://<meu domínio>/lumis/api/rest/lumsetlocale/pt_BR
    • http://<meu domínio>/lumis/api/rest/lumsetlocale/en_US

    Caso o ‘locale’ mencionado não seja suportado pelo portal, o idioma atual será mantido.

    Se o parâmetro não for especificado, o portal será retornado para o ‘locale’ padrão.

     

    Leitura de Interface REST

    Foi criada uma chamada capaz de consultar as informações contidas nos sources definidos nas interfaces REST. O formato básico é mostrado a seguir.

    {protocolo}://{domínio}[:porta]/lumis/api/rest/{nome-rest}/lumgetdata/{restinterface-name}[.returnType][parameters]

    • Protocol à são aceitas conexões via http e https.
    • Domínio/porta à domínio e porta de conexão do website.
    • nome-rest à nome REST da instância de serviço.
    • restinterface-name à nome da interface REST do serviço utilizado.
    • Return type à pode receber os valores ‘json’ ou ‘xml’, informando como será o retorno das informações (JSON ou XML, respectivamente – default ‘json’).

    Exemplos:

    • http://<meu domínio>/lumis/api/rest/noticias/lumgetdata/list
    • http://<meu domínio>/lumis/api/rest/noticias/lumgetdata/list.json

    Os parâmetros podem ser:

    • Número máximo de itens (lumMaxRows)

      Esse parâmetro é opcional e é utilizado como no exemplo a seguir, que traz as cinco primeiras notícias publicadas na instância de serviço chamada ‘noticias’.

      http://<meu domínio>/lumis/api/rest/noticias/lumgetdata/list.json?lumMaxRows=5

    • Primeiro item da lista (lumStartAt)

      Esse parâmetro é opcional e é utilizado como no exemplo a seguir, que traz a segunda página de notícias publicadas na instância de serviço chamada ‘noticias’, considerando cinco notícias por página.

      http://<meu domínio>/lumis/api/rest/noticias/lumgetdata/list.json?lumMaxRows=5&lumStartAt=6

    • Ordenação (lumOrderBy)

      Esse parâmetro é opcional e é utilizado para definir uma ordenação por um determinado campo em ordem crescente ou decrescente (ASC ou DESC respectivamente).

      O exemplo a seguir ordena as notícias adquiridas pelo seu titulo, de forma ascendente.

      http://<meu domínio>/lumis/api/rest/noticias/lumgetdata/list.json?lumMaxRows=5&lumStartAt=6&lumOrderBy=Title ASC

    • Campos retornados (lumReturnFields)

      Este parâmetro define quais campos deverão ser retornados. Por padrão, quando este parâmetro não for informado serão retornados todos os campos definidos explicitamente no source da interface REST juntamente com os campos "Chave primária do source" e o "Identificador de Conteúdo" (caso seja um serviço de conteúdo). Quando este parâmetro for informado os campos que serão retornados serão os definidos na lista de campos que devem ser separados por vírgula (",").
      Caso seja desejado o retorno de todos os campos basta informar "*" como valor do parâmetro lumReturnFields.

    O exemplo a seguir retorna os campos chave, identificador do conteúdo juntamente com os campos explícitos da interface REST.

    http://<meu domínio>/lumis/api/rest/noticias/lumgetdata/list.json

    O exemplo a seguir retorna os campos descrição e quem criou o conteúdo.

    http://<meu domínio>/lumis/api/rest/noticias/lumgetdata/list.json?lumReturnFields=createdBy,description

    O exemplo a seguir retorna todos campos do source.

    http://<meu domínio>/lumis/api/rest/noticias/lumgetdata/list.json?lumReturnFields=*

     

    Obtenção de um conteúdo através do seu slug

    O LumisXP possui uma funcionalidade para obter um conteúdo através do seu slug. Para isso, é necessário que os seguintes requisitos sejam atendidos:

    • O serviço deve ter uma interface REST de detalhes que conte com um filtro do identificador do conteúdo que seja lido do parâmetro de request lumItemId.
    • A instância de serviço onde o conteúdo foi cadastrado deve estar com o suporte REST habilitado.
    • O conteúdo deve ter sido cadastrado com um slug.

    Exemplo:
    Supondo que o serviço tenha uma interface REST chamada details que receba o identificador do conteúdo no parâmetro lumItemId e que a instância desse serviço esteja com suporte REST habilitado e que tenha um nome REST minha-instancia, um conteúdo de identificador EF179CC52E8444B88FC1CEDAF2E21939 poderia ter seus detalhes acessados através da URL http://meuservidor/lumis/api/rest/minha-instancia/lumgetdata/details?lumItemId=EF179CC52E8444B88FC1CEDAF2E21939.
    Agora, caso o conteúdo pertença a um source de identificador default e tenha um slug meu-conteudo, esse mesmo conteúdo também poderia ser acessado através da URL http://meuservidor/lumis/api/rest/minha-instancia/lumgetdata/details/default/meu-conteudo.

    Essa feature é especialmente importante quando o LumisXP é utilizado como um CMS headless.

     

    API de chamada de process action

    Foi criada uma chamada capaz de executar um dado process action. Esta chamada é destinada a ser usada tipicamente do navegador, mas não está limitada ao mesmo. Existem dois formatos básicos mostrados a seguir.

    POST {protocolo}://{domínio}[:porta]{contexto-da-aplicação}/lumis/api/rest/{nome-rest}/lumPA/{interfacesimple-id}.json POST {protocolo}://{domínio}[:porta]{contexto-da-aplicação}/lumis/api/rest/{nome-rest}/lumPA/{interfacesimple-id}/{lumaction-id}.json

    • protocolo: são aceitas conexões via http e https.
    • domínio / porta: domínio e porta de conexão do website.
    • contexto-da-aplicação: contexto na qual a aplicação é executada ou string vazia, caso a aplicação seja executada na raiz. Por exemplo: /portal.
    • nome-rest: nome REST da instância de serviço.
    • interfacesimple-id: identificiador simples da interface. É a parte após o último . do identificador da interface. Por exemplo, na interface lumis.service.news.add seria add.
    • lumaction-id: identificador do process action. Exemplo: commit.

    Exemplos:

    • http://<meu domínio>/lumis/api/rest/noticias/lumPA/add.json
    • http://<meu domínio>/lumis/api/rest/noticias/lumPA/add/commit.json

     

    Help da API de chamada de process action

    Foi criada uma chamada capaz de consultar os controles da interface solicitada e retornar como resposta as definições dos parâmetros do request. O formato básico é mostrado a seguir.

    GET {protocolo}://{domínio}[:porta]{contexto-da-aplicação}/lumis/api/rest/{nome-rest}/lumPA/{interfacesimple-id}/help

    • protocolo: são aceitas conexões via http e https.
    • domínio / porta: domínio e porta de conexão do website.
    • contexto-da-aplicação: contexto na qual a aplicação é executada ou string vazia, caso a aplicação seja executada na raiz. Por exemplo: /portal.
    • nome-rest: nome REST da instância de serviço.
    • interfacesimple-id: identificiador simples da interface. É a parte após o último . do identificador da interface. Por exemplo, na interface lumis.service.news.add seria add.

    Exemplo:

    • http://<meu domínio>/lumis/api/rest/noticias/lumPA/add/help

     

    Verificar se usuário é membro de grupo

    Verifica se o usuário logado é membro de um dado grupo. Responde com um json de um objeto com propriedade 'result' tipo boolean que indica se é ou não membro.

    GET {protocolo}://{domínio}[:porta]{contexto-da-aplicação}/lumis/api/rest/lumis/autentication/users/current/isMemberOf/{groupAlias}

    • protocolo: é o protocolo de acesso ao portal (normalmente, http ou https).
    • domínio / porta: domínio e porta de conexão do website, onde a porta pode ser omitida caso seja padrão. Exemplos: meuwebsite.com:8080, meuwebsite.com.br etc.
    • contexto-da-aplicação: contexto na qual a aplicação é executada ou string vazia, caso a aplicação seja executada na raiz. Por exemplo: /portal.
    • groupAlias: O apelido do grupo na qual será feita a verificação. Exemplo: admins, cadastrados etc

    Exemplo de corpo de resposta

    Exemplo de uso

     

    Obtém informação da geolocalização do usuário

    Obtém informação da geolocalização do usuário. Esta informação é baseada no endereço IP do usuário, e por isso pode não possuir precisão ou até mesmo estar disponível, mas geralmente apresenta um bom resultado com granularidade de cidade. É uma alternativa ao uso da API javascript de geolocation, que para funcionar requer permissão do usuário e disponibilidade no dispositivo em uso.

    GET {protocolo}://{domínio}[:porta]{caminho-do-website}/lumis/api/rest/lumis/geolocation/currentPosition

    • protocolo: é o protocolo de acesso ao portal (normalmente, http ou https).
    • domínio / porta: domínio e porta de conexão do website, onde a porta pode ser omitida caso seja padrão. Exemplos: meuwebsite.com:8080, meuwebsite.com.br etc.
    • caminho-do-website: é o caminho do website conforme cadastrado no website. Pode ser string vazia, caso a URL do website seja na raiz. Por exemplo: /portal.

    Exemplo de corpo de resposta

    Caso não tenha sido possível identificar a geolocalização do usuário, o corpo da resposta será um objeto vazio {}.

    Exemplo de uso

     

    Solução de problemas

    Para possíveis soluções de problemas, veja essa página.