Implementar uma API Personalizada para um Serviço REST do Façade

Quando você desenvolve um aplicativo móvel, geralmente começa com a camada da interface do usuário primeiro e, em seguida, conecta seu aplicativo a outro aplicativo usando serviços Web REST. Esta abordagem funciona bem para aplicações pequenas ou simples. Quando os aplicativos são maiores e você deseja se conectar a vários serviços de back-end, pode inadvertidamente apresentar problemas de desempenho e segurança.

É uma prática recomendada começar a construir uma camada de API de fachada entre os serviços de back-end externos e a interface do usuário para reduzir o número de chamadas para os serviços de back-end sempre que possível. Por exemplo, seu aplicativo móvel pode executar uma única chamada para a camada de API da fachada, que trata as chamadas para outros serviços REST e consolida todos os dados recebidos em uma única resposta ao seu aplicativo móvel.

Criar uma API Personalizada Completa

Para criar uma API personalizada completa usando o Oracle Mobile Hub.

Clique em e selecione Desenvolvimento e, em seguida, APIs no menu lateral. Se uma API já tiver sido criada (seja em um estado Rascunho ou Publicado), você verá uma lista de APIs. Se não houver APIs personalizadas, você verá uma página com o botão Nova API. Clique na API que você já criou ou clique em Nova API para começar.

Definir Pontos Finais

Você cria recursos para definir os pontos finais da sua API. Um recurso é o ponto crucial de uma API. Ele tem um tipo, alguns dados associados a ele, um relacionamento com outros recursos e contém um ou mais métodos que atuam nele. Um recurso pode ser praticamente qualquer coisa: uma imagem, um arquivo de texto, uma coleção de outros recursos, uma transação lógica, um procedimento, etc.

Clique no link de navegação Pontos Finais para começar.
Clique em Novo Recurso e adicione algumas informações básicas.

Cada vez que você clica em Novo Recurso, cria um recurso de nível superior (raiz). Se quiser adicionar um recurso filho (aninhado), clique em Adicionar (+) ao lado do recurso de nível superior. Clique em X para excluir um recurso.

Observação:
Consulte os ícones nos links Métodos? Cada vez que você define um método para um recurso, um ícone para ele aparece no link Métodos. Use-os como atalhos para ver quais métodos já foram definidos para um recurso. Clique em um ícone para ir diretamente para sua definição na página Métodos.
Forneça o caminho do recurso, que é o URI (relativo ao URI base). Por exemplo, se o URI base for /mobile/custom/audits/, você poderá adicionar o recurso, findings, que é /mobile/custom/audits/findings.
Forneça o nome para exibição, que é um nome para o recurso que facilita a identificação na documentação da API.
Os recursos são listados por seus nomes de exibição no lado esquerdo da página Teste de API.
Fornece uma breve descrição do recurso.

Depois que você informar uma descrição, o URI será exibido abaixo do campo de descrição.
(Opcional) Forneça um tipo de recurso RAML, que é o tipo de recurso (resourcesType:). Não é necessário especificar um tipo de recurso. Se você quiser usar um tipo de recurso, mas não tiver um definido, clique no link Tipos e defina um.

Quando você cria um método para um recurso, um símbolo para esse método aparece abaixo do link Métodos. Você pode ver imediatamente quais métodos são definidos para um recurso se precisar examinar uma definição de recurso. Clique em um ícone para ir diretamente para essa definição de método.

Você pode limpar a bagunça para localizar um recurso mais rapidamente alternando para o Modo Compacto (ele está à direita de Novo Recurso). A exibição compacta oculta a descrição do recurso, o tipo de recurso e o caminho.

Adicionar Métodos aos Seus Recursos

Métodos são ações que podem ser executadas em um recurso. A página Métodos mostra um método por vez. Depois que pelo menos dois métodos forem definidos, você poderá clicar no ícone de um método na parte superior da página para ver seus detalhes.

Adicione alguns métodos ao recurso clicando em Métodos.

Se o recurso para o qual você está definindo métodos tiver parâmetros de caminho, eles serão exibidos acima de Adicionar Método.
1. (Opcional) Clique em Obrigatório se quiser que os parâmetros de caminho sejam informados com cada método.
  O nome do parâmetro é exibido.
2. Forneça um nome para exibição do parâmetro e do código de exemplo.
3. Na lista drop-down, selecione o tipo de valor válido para o parâmetro.
Clique em Adicionar Método e selecione o método desejado.

Depois de selecionar um método, ele não será mais listado na lista de métodos porque você usa um método apenas uma vez por recurso (por exemplo, você não pode definir dois métodos DELETE para um único recurso). Um ícone para cada método definido é exibido na parte superior da página. Clique em um ícone de método para ir diretamente para sua definição.
(Opcional) Informe uma breve descrição do método no campo Descrição.
(Opcional) Informe um nome para exibição para o método.
(Opcional) Forneça quaisquer características a serem aplicadas ao método.

Se você não tiver nenhuma característica de recurso definida, clique em Pontos Finais para voltar à página Recursos principal e clique no link Características para definir uma. As características permitem definir um conjunto de operações semelhantes.

Depois de definir métodos para o recurso, você pode definir as solicitações e respostas para esses métodos.

Definir uma Solicitação do Método

Agora que você selecionou um método, defina a solicitação que está fazendo do serviço ao qual deseja se conectar. Por exemplo, se você selecionou um método POST, agora poderá definir o que criar. Você faz isso adicionando parâmetros e um corpo de solicitação, que contém a descrição dos dados a serem enviados ao serviço.

Clique em Solicitação para definir uma solicitação.
Clique em Adicionar Parâmetro e selecione um tipo de parâmetro: Consulta ou Cabeçalho. Selecione Obrigatório se o parâmetro for obrigatório para o método.
1. Dê ao parâmetro um nome e um nome para exibição.
2. Selecione um tipo de valor válido: String, Número, Inteiro, Data ou Booliano.
3. (Opcional) Forneça uma descrição do parâmetro e um exemplo que você possa usar ao testar a validade do ponto final. Por exemplo, você pode ter um recurso, audits, e adicionar um parâmetro de consulta, auditorID, que usa um valor numérico, e outro parâmetro, auditName, que usa um valor de string:
```
/audits: 
  get: 
    description: | 
      Gets list of audits, organizations etc.     
    queryParameters: 
      auditorID:  
        id: Auditor ID
        description: | 
          display auditor identifier 
        type: integer 
        example: |
          1234
        required: false      
      auditName:
        displayName: auditName
        description: |
          Audit name
        example: "Payroll Process Audit"
```
  Neste exemplo, um método GET é definido com os parâmetros de consulta, auditorID e auditName.
4. (Opcional) Clique em Mais Propriedades para adicionar propriedades aninhadas ao parâmetro. Clique em Repetir para adicionar múltiplos do parâmetro atual.
5. Clique em Adicionar Parâmetro para adicionar outro parâmetro de nível superior para o método.
Dependendo do método selecionado, clique em Adicionar Tipo de Mídia e defina o corpo do método. O corpo contém os dados que você está enviando para o servidor. Por exemplo, se você estiver definindo um método POST, precisará definir o item que está criando, como uma nova listagem de clientes ou solicitação de serviço. Se você estiver definindo um método GET, não precisará enviar um corpo de método para não precisar especificar um tipo de mídia.
1. Selecione o tipo de mídia para o corpo do método, que é o formato da mensagem que você está enviando, como texto, imagens ou formulários da Web.
  Dependendo do tipo (por exemplo, você não informaria um esquema para um tipo de imagem), terá a opção de adicionar um esquema, um exemplo ou ambos.
  Ao definir um esquema, adicione apenas os dados necessários para a finalidade do recurso. Ou seja, não adicione dados desnecessários que apenas retardem a transmissão e aumentem potencialmente o potencial de erros.
2. (Opcional) Clique em Esquema e informe um esquema (no formato JSON) no painel do editor. Um esquema é como um modelo para o corpo. É o que você usa para definir o conteúdo da mensagem.
3. (Opcional) Clique em Exemplo e informe um exemplo (no formato JSON) no painel do editor, que é usado pela implementação simulada como uma resposta simulada para o método. O uso de dados simulados pode ajudá-lo a verificar o comportamento de seus métodos. O exemplo mostra valores simulados para os dados que estão sendo enviados no corpo da mensagem, conforme definido no método POST do recurso audits:
```
body: 
  application/json: 
    example: | 
      { 
        "Title": "Leaking Water Heater",
        "Username": "joh1017",  
        "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014", 
        "Notes": "my water heater is broken"
      }                               
```
Clique em Adicionar Tipo de Mídia para adicionar outros tipos de mídia. Se você decidir que não quer o método, clique em X no banner para excluí-lo.

Definir uma Resposta para o Método

Dependendo da solicitação, você pode ou não precisar de uma resposta. Uma resposta descreve o processo para retornar resultados do serviço. Talvez você queira definir uma resposta que verifique se os dados solicitados foram retornados ou uma resposta que reconheça se a solicitação foi ou não recebida. Definir uma resposta é semelhante a definir uma solicitação. A principal diferença é que você precisará selecionar um código de status para informar o resultado da conexão.

Clique em Resposta para definir uma ou mais respostas.
Clique em Adicionar Resposta e selecione o código de status que deseja retornar.
Um código de status 200 é fornecido por padrão, mas se esse não for o código desejado, selecione um na lista suspensa.
- 2xx indica que uma conexão bem-sucedida.
- 3xx indica que ocorreu um redirecionamento.
- 4xx indica que ocorreu um erro do usuário.
- 5xx indica que ocorreu um erro de servidor.
Para ajudar quem usa a API a entender o motivo de um possível erro na API que você está configurando, use um código de status HTTP para retornar um código que melhor corresponda à situação de erro.
Forneça uma descrição do que o código designa.
Clique em Adicionar Cabeçalho, selecione um Cabeçalho ou Consulta de resposta, forneça o nome do cabeçalho ou da consulta e um nome para exibição do cabeçalho e o tipo de valor válido do cabeçalho.
Clique em Adicionar Tipo de Mídia e selecione o formato da resposta. Dependendo do tipo de mídia selecionado, você pode adicionar parâmetros, esquemas ou exemplos da mesma forma que fez com o corpo da Solicitação.
1. Para o tipo de mídia baseada em texto (por exemplo, application/json ou text/xml), clique em Esquema para informar um esquema (no formato JSON) para o corpo.
  Como no corpo da solicitação, adicione apenas dados pertinentes ao corpo da resposta. Não inclua mais dados do que você realmente precisa para a operação.
2. Clique em Exemplo para adicionar dados simulados (no formato JSON) para seu corpo de resposta. Use dados simulados para verificar o comportamento dos métodos antes de testar com dados reais.
3. Para o tipo de mídia baseado em form (por exemplo, multipart/form-data), clique em Adicionar Parâmetro e selecione Obrigatório se o parâmetro for obrigatório. Em seguida, forneça um nome e selecione um tipo de valor. Opcionalmente, você pode dar um nome ao seu parâmetro.
4. Para o tipo de mídia baseado em imagem (por exemplo, image/png), você não precisa fazer nada porque não há esquemas ou atributos a serem fornecidos.

O exemplo a seguir mostra que uma resposta para o método POST do recurso audits foi criada com um código de status de 201 indicando que um novo recurso foi criado com sucesso. O exemplo também mostra um formato de resposta de retorno application/json, um cabeçalho Location que foi adicionado e o corpo da mensagem que contém dados simulados:

responses: 
  201: 
    description: | 
      The request has been fulfilled and resulted in a new resource 
      being created. The newly created resource can be referenced  
      by the URI(s)returned in the entity of the response, with the 
      most specific URI for the resource given by a Location header
      field.  

    headers:
      Location:
        displayName: Location
        description: |
          Identifies the location of the newly created resource.

        type: string
        example: |
          /20934

        required: true

    body: 
      application/json: 
        example: | 
          {
            "id": 20934,
            "title": "Lynn's Leaking Water Heater",
            "contact": {
               "name": "Lynn Adams",                 
               "street": "45 O'Connor Street",
               "city": "Ottawa", 
               "postalcode": "a1a1a1",
               "username": "johnbeta"
              },
           "status": "New",
           "driveTime": 30,
           "priority": "high",
           "notes": "My notes",
           "createdon": "2014-01-20 23:15:03 EDT",
           "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d74331d77/objects/6cdaa3a8-097e-49f7--9bd2-88966c45668f?user=lynn1014"
          }

Ao definir sua resposta, você pode decidir testar seus pontos finais ou clicar em Pontos Finais na barra de navegação para retornar à página principal Recursos. A partir daí, você pode prosseguir para outra página no API Designer para criar uma raiz, tipos de recursos ou características ou adicionar documentação da API.

Se você decidir não querer o método, clique em X no banner para excluí-lo.

Criar uma API de Conector REST

Use o assistente de API do Conector REST para criar, configurar e testar sua API do conector.

Para obter uma API de conector de trabalho básica, você pode fornecer apenas um nome para a API de conector e um URL para o serviço externo.

A partir daí, você pode:

Defina regras para formar solicitações ou respostas específicas para os dados que você deseja acessar.
Configure políticas de segurança do cliente para o serviço que você está acessando.
Teste a conexão e teste os resultados das chamadas feitas à conexão.

Você deve criar uma API e implementação personalizadas para permitir que seus aplicativos chamem as APIs do conector e gerem a API e a implementação automaticamente. Se quiser fazer isso manualmente, crie uma API personalizada com os recursos apropriados e implemente o código personalizado.

Configurar um Conector Básico

Você pode criar um conector funcional concluindo as duas primeiras páginas no assistente de API do Conector REST.

Clique em e selecione Desenvolvimento e, em seguida, APIs no menu lateral.
Clique em REST (se esta for a primeira API do conector a ser criada) ou em Novo Conector e, na lista drop-down, selecione REST.
Identifique sua nova API de conector REST fornecendo o seguinte:
1. Nome para Exibição da API: O nome como ele aparecerá na lista de APIs do conector.
2. Nome da API: O nome exclusivo da sua API do conector.
  
  Por padrão, esse nome é anexado ao URI base relativo como o nome do recurso da API do conector. Você pode ver o URI base abaixo do campo Nome da API.
  
  Além de uma nova versão desta API do conector, nenhuma outra API do conector pode ter o mesmo nome de recurso.
3. Descrição Curta: Essa descrição será exibida na página Conectores quando essa API for selecionada.
Clique em Criar.
Na página Geral da caixa de diálogo API do Conector REST, defina os valores de timeout:
- Timeout de Leitura HTTP: O tempo máximo (em milissegundos) que pode ser gasto na espera para ler os dados. Se você não fornecer um valor, o valor padrão de 20 segundos será aplicado.
- Timeout de Conexão HTTP: O tempo (em milissegundos) gasto na conexão com o URL remoto. Um valor de 0mms significa que um timeout infinito é permitido.
  
  Os valores de timeout HTTP devem ser menores que a política Network_HttpRequestTimeout, que tem um valor padrão de 40.000 ms.
  
  Observação:
  Se você tiver uma função de administrador de nuvem móvel além da sua função de desenvolvedor de serviço, poderá abrir o arquivo policies.properties para ver o valor das políticas de rede do ambiente atual na exibição Administrador. Caso contrário, peça ao administrador da nuvem móvel os valores.
Clique em Descritor e especifique as informações de conexão do serviço.

Se você fornecer um URL do descritor do Swagger, os recursos disponíveis serão identificados e exibidos, e você poderá selecionar quais deseja.

Observação:
Somente as portas padrão de acesso à Internet 80 e 443 são suportadas. Não é possível estabelecer conexão com um serviço usando uma porta personalizada.
Clique em Salvar.
(Opcional) Clique em Testar, selecione credenciais de autenticação e faça chamadas de teste para o serviço.

A partir daí, você pode configurar ainda mais o conector das seguintes maneiras:

(Se você tiver fornecido um descritor na página Descritor), vá para a página Recursos e selecione os métodos para os recursos expostos.
Definir regras.
Definir políticas de segurança.

Para garantir que a configuração da API do conector seja válida, você deve testá-la completamente (não apenas na página Teste da API do Conector) antes de publicá-la. Ou seja, você também deve testar a API personalizada (com sua implementação) que usa essa API de conector. Essencialmente, se você estiver pronto para publicar a API do conector, também deverá estar pronto para publicar a API personalizada que a chama.

Definir Regras

Defina regras para definir as interações entre seu aplicativo móvel e um serviço. As regras fornecem uma maneira de adicionar valores de parâmetro padrão para todas as chamadas para recursos no serviço, chamadas para um caminho de proxy específico e chamadas para determinados tipos de operações (verbos). Isso ajuda a impor uma sintaxe consistente da string de URL, evita que o desenvolvedor de código personalizado precise inserir esses valores e permite rastrear as diferentes chamadas por meio de análises.

Você pode criar uma ou mais regras. Cada regra pode ter um ou mais parâmetros do tipo Query e Header.

Se nenhuma regra for aplicada, todas as chamadas serão passadas pelo proxy para o serviço existente.

Se o conector ainda não estiver aberto, clique em e selecione Desenvolvimento e, em seguida, APIs no menu lateral.
Selecione a API do conector que você deseja editar e clique em Abrir.
Selecione Atribuições.
Clique em Nova Regra.
Clique em Adicionar Parâmetro e selecione um tipo de parâmetro Consulta ou Cabeçalho e informe o nome da consulta ou do cabeçalho e seu valor.

Observação:

Embora você possa definir regras para definir determinados cabeçalhos por padrão, as regras não serão aplicadas se o cliente que chamou o conector diretamente por meio de código personalizado ou indiretamente, como de um navegador da Web ou aplicativo móvel, já tiver definido os mesmos cabeçalhos.

Especificamente, a definição do formato do corpo da solicitação geralmente é feita no código personalizado com o cabeçalho Content-Type, não como uma regra do Conector REST. Da mesma forma, a definição do formato do corpo da resposta também é feita no código personalizado com o cabeçalho Accept, não como uma regra do Conector REST.

Você pode adicionar quantos parâmetros desejar a uma regra, mas é melhor não sobrecarregar uma regra com muitas operações. Uma construção de regra mais simples é mais fácil de solucionar problemas.
Expanda Recursos e edite o URL remoto para fornecer um recurso à regra a ser aplicada. O valor do URL base é o que você inseriu na etapa de definição de informações básicas e não pode ser editado.
Selecione Não aplicar a recursos de nível inferior se quiser que as regras sejam aplicadas apenas ao nível de recurso especificado no URL Remoto.
(Opcional) Desmarque os métodos HTTP que você não deseja aplicar às regras que acabou de definir. Por padrão, todos os métodos são selecionados.
(Opcional) Clique em Nova Regra para criar outra regra.

Observação:

Se você definir uma regra em conflito com outra regra, a primeira regra aplicada terá precedência e a regra em conflito será ignorada.

Quando terminar, clique em Salvar e, em seguida, clique em Próximo (>) para ir para a próxima etapa na configuração da API do conector.

A descrição da regra que você acabou de definir é mostrada no banner Regra logo acima da seção Parâmetros Padrão. Por exemplo, digamos que os seguintes valores tenham sido fornecidos:

URL Remoto = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle
URI Local = myMapAPI
Regra com o seguinte parâmetro: Query:key:A3FAEAJ903022
Métodos HTTP GET e PUT

A descrição da regra seria a seguinte:

Para GET a https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle disponível em myMapAPI/directions, inclua Query:key=A3FAEAJ903022.

Se nenhuma regra fosse criada, a descrição seria:

Para ALL METHODS to https://maps.googleapis.com/maps/api/directions disponível em myMapAPI, nenhum parâmetro padrão será aplicado.

Agora você tem um URI base que é mapeado para o serviço existente. Usando nosso exemplo:

mobile/connector/myMapAPI/directions/json?origin=los+angeles&destination=seattle mapeia para https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

Configurar Políticas de Segurança e Propriedades de Substituição

Antes de finalizar a API do conector, considere como lidar com sua segurança. Você pode usar políticas de segurança ou cabeçalhos de autorização. A seleção de uma política de segurança que descreva o esquema de autenticação do serviço ao qual você está se conectando é a abordagem recomendada.

Toda política de segurança tem propriedades, chamadas substituições, que você pode configurar. Um motivo para substituir uma propriedade de configuração de política é limitar o número de políticas que você precisa manter: em vez de criar várias políticas com configurações ligeiramente variadas, você pode usar a mesma política genérica e substituir valores específicos para atender aos seus requisitos.

Para selecionar uma política de segurança e definir as substituições de política:

Se o conector ainda não estiver aberto, clique em e selecione Desenvolvimento e, em seguida, APIs no menu lateral.
Selecione a API do conector que você deseja editar e clique em Abrir.
Selecione Segurança.
Selecione a política de segurança na lista de políticas disponíveis e clique na seta para a direita para movê-la para a lista Políticas Selecionadas.
Selecione apenas uma única política para sua API de conector. Uma descrição de uma política selecionada é exibida abaixo da lista.
Especifique substituições, se aplicável, à política selecionada se você não quiser usar os valores padrão.
Para substituir uma propriedade, insira ou selecione um valor diferente do padrão.
Clique em Salvar para salvar seu trabalho ou clique em Salvar e Fechar para salvar seu trabalho e sair do assistente de API do Conector REST.
Clique em Próximo (>) para avançar para a próxima etapa.