Criação de REST API

Extensões da API REST

Crie extensões de API REST para usar dados de sistemas de terceiros (bancos de dados, serviços web, Bonita Engine, etc) em formulários e páginas.

As extensões da API REST podem ser usadas para consultar dados de negócios, APIs do Bonita Engine ou um sistema de informações externo (como um banco de dados, serviço da Web, diretório LDAP…). Eles também ajudam a manter uma separação clara entre o front-end (formulários, páginas e interfaces visíveis para os usuários) e o back-end (processos).

Exemplo

As seções a seguir mostram como criar uma extensão de API REST. Como exemplo, criamos uma extensão de API REST que usa o Bonita BPM Engine para fornecer informações do usuário (nome, sobrenome, endereço de e-mail).

Gerar um novo esqueleto de extensão da API REST

• No menu Desenvolvimento, escolha REST API Extension e, em seguida, New…​.

• Insira um nome, por exemplo, informações do usuário, extensão da API REST.

• Insira uma Descrição, por exemplo, Query Bonita Engine para recuperar informações do usuário.

• Insira um nome de pacote, use para definir o ID do grupo do artefato, por exemplo: com.company.rest.api

• Insira um nome de projeto, por exemplo userInformationRestAPIExtension

• Clique em Avançar.

• Insira o pathTemplate para esta extensão da API REST, por exemplo userInformation. Este será o ponto de
  acesso da API e segue este padrão: {bonita_context}/API/extension/userInformation.

• Como essa extensão da API REST não acessa dados corporativos, você pode desmarcar com segurança a caixa de seleção "Adicionar dependências BDM".

• Defina um nome de permissão para a extensão (substitua o padrão), por exemplo read_user_information. Este é o nome da permissão que os usuários devem ter para ter acesso à extensão (consulte Uso de extensões da API REST)

• Clique em Avançar

• Esta tela define os parâmetros de URL que serão passados ​​para a API. Por padrão, os parâmetros p e c são definidos para habilitar o resultado paginado, isso se aplica bem em nossos exemplos, pois queremos retornar uma lista de usuários.

• Clique em Criar.

Escreva o código

O primeiro passo seria remover arquivos e códigos relacionados à configuração da API REST, pois não precisamos definir parâmetros de configuração para nossa API REST:

Excluir configuration.properties da pasta src/main/resources

Excluir testConfiguration.properties de src/test/resources

Remova a configuração do arquivo de configuração mock. Edite IndexTest.groovy, vá para o método setup() e remova a linha que começa com resourceProvider....

Remova o exemplo de uso de configuração no arquivo Index.groovy (veja o comentário começando com: "Here is an example...").

Agora podemos adicionar nossa lógica de negócios. Em Index.groovy, no método doHandle, localize o comentário "Your code goes here" e adicione o código abaixo no seu(removendo o result existente e a declaração de retorno):
// Convert parameters from string to int p = p as int c = c as int

// Initialize the list to store users information def usersInformation = []

// Get the list of user List<User> users = context.apiClient.identityAPI.getUsers(p*c, c, UserCriterion.FIRST_NAME_ASC)

// Iterate over each user for (user in users) { // Get user extra information (including email address) ContactData contactData = context.apiClient.identityAPI.getUserContactData(user.id, false)

// Create a map with current user first name, last name and email address def userInformation = [firstName: user.firstName, lastName: user.lastName, email: contactData.email]

// Add current user information to the global list usersInformation << userInformation }

// Prepare the result def result = [p: p, c: c, userInformation: usersInformation]

int startIndex = p*c int endIndex = p*c + users.size() - 1

// Send the result as a JSON representation return buildPagedResponse(responseBuilder, new JsonBuilder(result).toString(), startIndex, endIndex, context.apiClient.identityAPI.numberOfUsers) CTRL+SHIFT+O para importar o que faltar

Teste o código-fonte

Agora precisamos atualizar o teste para verificar o comportamento de nossa extensão de API REST editando IndexTest.groovy.

O primeiro passo é definir alguns mocks para nossas dependências externas, como a API Engine Identity. Adicione a seguinte declaração de mocks após as existentes:

def apiClient = Mock(APIClient) 

def identityAPI = Mock(IdentityAPI) 

def april = Mock(User) 

def william = Mock(User)

def walter = Mock(User) 

def contactData = Mock(ContactData)

Agora precisamos definir o comportamento genérico de nossos mocks. O método setup() deve ter o seguinte conteúdo: context.apiClient >> apiClient
apiClient.identityAPI >> identityAPI


identityAPI.getUsers(0, 2, _) >> [april, william]
identityAPI.getUsers(1, 2, _) >> [william, walter]
identityAPI.getUsers(2, 2, _) >> [walter]


april.firstName >> "April"
april.lastName >> "Sanchez"
william.firstName >> "William"
william.lastName >> "Jobs"
walter.firstName >> "Walter"
walter.lastName >> "Bates"


identityAPI.getUserContactData(*_) >> contactData
contactData.email >> "test@email"


Agora você pode definir um método de teste. Substitua o método should_return_a_json_representation_as_result existente pelo seguinte:

def should_return_a_json_representation_as_result() {

 given: "a RestAPIController"
 def index = new Index()
 // Simulate a request with a value for each parameter
 httpRequest.getParameter("p") >> "0"
 httpRequest.getParameter("c") >> "2"
 when: "Invoking the REST API"
 def apiResponse = index.doHandle(httpRequest, new RestApiResponseBuilder(), context)
 then: "A JSON representation is returned in response body"
 def jsonResponse = new JsonSlurper().parseText(apiResponse.response)
 // Validate returned response
 apiResponse.httpStatus == 200
 jsonResponse.p == 0
 jsonResponse.c == 2
 jsonResponse.userInformation.equals([
   [firstName:"April", lastName: "Sanchez", email: "test@email"],
   [firstName:"William", lastName: "Jobs", email: "test@email"]
 ]);

}

Certifique-se de adicionar todas as importações ausentes (atalho padrão CTRL+SHIFT+o).

Agora você deve ser capaz de executar seu teste de unidade. Clique com o botão direito do mouse no arquivo IndexTest.groovy e clique em REST API Extension > Run JUnit Test. A visualização JUnit exibe os resultados do teste. Todos os testes devem passar.

Build, deploy e teste a extensão REST API

O Studio permite que você crie e implante a extensão da API REST no ambiente de teste incorporado.

A primeira etapa é configurar o mapeamento de segurança para sua extensão no ambiente de teste incorporado do Studio:

• No menu Desenvolvimento, escolha REST API Extension e Edit permissions mapping.

• Acrescente esta linha no final do arquivo: profile|User=[read_user_information] Isso significa que qualquer pessoa logada com o perfil de usuário recebe essa permissão.

• Salve e feche o arquivo.

Agora você pode realmente compilar e implantar a extensão:

• No menu Desenvolvimento, escolha REST API Extension > Deploy…​

• Selecione a extensão da API REST userInformationRestAPIExtension.

• Clique no botão Implantar.

• Na coolbar, clique no ícone Aplicativos. Isso abre o Diretório de aplicativos Bonita em seu navegador.

• Acesse o Aplicativo Administrador do Bonita

• Vá para a guia Recursos e verifique se a extensão da API REST de informações do usuário está na lista de recursos de extensão da API REST.

Agora você pode finalmente testar sua extensão da API REST:

• Abra uma nova guia no navegador da web

• Insira o seguinte URL: http://localhost:8080/bonita/API/extension/userInformation?p=0&c=10.

• O corpo da resposta JSON deve ser exibido.

A extensão da API REST pode ser usada em formulários e páginas no UI Designer usando uma variável de API externa.