Implemente uma API Personalizada para um Serviço REST Façado

Ao desenvolver uma aplicação móvel, você normalmente inicia com a camada da interface do usuário e depois conecta sua aplicação com outra usando os Web services do REST. Essa abordagem funciona bem para aplicações pequenas ou simples. Quando as aplicações forem maiores e você quiser estabelecer conexão com vários serviços de back-end, poderá inadvertidamente introduzir problemas de desempenho e segurança.

É uma melhor prática começar a criar uma camada de API faziosa 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, sua aplicação móvel pode executar uma chamada única para a camada da API mais lenta que trata as chamadas para outros serviços do REST e consolida todos os dados de entrada em uma única resposta para sua aplicação 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 de sua API. Um recurso é o crux 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 agem nele. Um recurso pode ser quase algo: uma imagem, um arquivo de texto, um conjunto 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ê clicar em Novo Recurso , criará um recurso (raiz) de nível superior. 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/, então você poderia adicionar o recurso, findings, ou seja /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 de Teste da 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ê poderá ver imediatamente quais métodos serã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 desorganização 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 de cada 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 que você estiver 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 do caminho sejam transmitidos com cada método.
  O nome do parâmetro é exibido.
2. Forneça um nome para exibição para o parâmetro e o código de exemplo.
3. Na lista suspensa, selecione o tipo de valor válido para o parâmetro.
Clique em Adicionar Método e selecione o método que deseja.

Depois de selecionar um método, ele não é mais listado na lista de métodos porque você usa um método somente uma vez por recurso (por exemplo, não é possível definir dois métodos DELETE para um único recurso). Um ícone para cada método que você definir será 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 do método.
(Opcional) Forneça qualquer característica a ser aplicada ao método.

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

Depois de definir métodos para o recurso, você poderá 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 você deseja se conectar. Por exemplo, se você selecionou um método POST, agora você pode 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 necessário para o método.
1. Dê um nome ao parâmetro 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ê pode 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 estiver definindo um método POST, você precisará definir o item que está criando, como uma nova listagem de clientes ou solicitação de serviço. Se estiver definindo um método GET, não será necessário enviar um corpo de método para que você não precise especificar um tipo de mídia.
1. Selecione o tipo de mídia para o corpo do seu método, que é o formato da mensagem que você está enviando, como texto, imagens ou forms Web.
  Dependendo do tipo (por exemplo, você não informa um esquema para um tipo de imagem), você tem a opção de adicionar um esquema ou um exemplo, ou ambos.
  Ao definir um esquema, adicione apenas os dados necessários para o objetivo do recurso. Ou seja, não adicione dados desnecessários que reduzirão somente a transmissão e potencialmente aumentarão 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 insira 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 tipos de mídia adicionais. Se você decidir que não deseja o método, clique em X no banner para excluí-lo.

Definir uma Resposta para o Método

Dependendo da solicitação, talvez você não precise de uma resposta. Uma resposta descreve o processo para retornar resultados do serviço. Você pode definir uma resposta que verifica se os dados solicitados foram retornados ou pode querer que uma resposta que confirme se a solicitação foi ou não recebida. A definição de uma resposta é semelhante à definição de uma solicitação. A diferença principal é 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.
O código de status 200 é fornecido por padrão, mas se esse não for o código desejado, selecione um na lista suspensa.
- 2 xx indica que uma conexão foi bem-sucedida.
- 3 xx indica que ocorreu um redirecionamento.
- 4 xx indica que ocorreu um erro do usuário.
- 5 xx indica que ocorreu um erro do servidor.
Para ajudar a usar a API para entender o motivo de um possível erro na API que você está configurando, use um código de status HTTP para retornar o código que melhor corresponda à situação do 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 de exibição para o cabeçalho e o tipo de valor válido para o 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 exatamente como fez no corpo da Solicitação.
1. Para o tipo de mídia baseado 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 realmente necessários para a operação.
2. Clique em Exemplo para adicionar dados simulados (no formato JSON) para o corpo da sua resposta. Use dados simulados para verificar o comportamento de seus métodos antes de testá-los 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 fornecer um nome ao parâmetro.
4. Para o tipo de mídia baseado em imagem (por exemplo, image/png), não é necessário 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 201 indicando que um novo recurso foi criado com sucesso. O exemplo também mostra um formato de resposta de retorno de 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 de Recursos. Nessa página, você pode prosseguir para outra página no API Designer para criar uma raiz, tipos de recursos ou características, ou ainda adicionar uma documentação da API.

Se você decidir que não deseja 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 de conector.

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

Nessa página, você pode:

Defina regras para formar solicitações ou respostas específicas dos dados que 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 uma 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, você precisa criar uma API personalizada com os recursos apropriados e, em seguida, implementar o código personalizado.

Configurar um Conector Básico

Você pode criar um conector funcional preenchendo as duas primeiras páginas no assistente da 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 a nova API do 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 API do conector.
  
  Por default, esse nome é acrescentado ao URI base relativo como o nome do recurso para a API do conector. Você pode ver o URI base abaixo do campo Nome da API .
  
  Diferente de uma nova versão desta API de conector, nenhuma outra API de 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 do 0mms significa que é permitido um timeout infinito.
  
  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 atribuição de administrador de nuvem móvel além da atribuiçã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 view Administrador. Caso contrário, solicite ao administrador da nuvem móvel os valores.
Clique em Descritor e insira as informações de conexão para o serviço.

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

Observação:
Somente as portas de acesso à Internet padrão 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 as credenciais de autenticação e faça as chamadas de teste para o serviço.

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

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

Para certificar-se de que a configuração da API do conector seja válida, teste-a completamente (não apenas na página de 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 deve estar pronto para publicar a API personalizada que a chama.

Definir Regras

Você define 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 a um caminho de proxy específico e chamadas para determinados tipos de operações (verbos). Isso ajuda a aplicar uma sintaxe consistente da string de URL, salva o desenvolvedor de código personalizado de ter que inserir esses valores e tornar possível rastrear as diferentes chamadas por meio de análise.

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 Funções .
Clique em Nova Regra.
Clique em Adicionar Parâmetro e selecione um tipo de parâmetro de Consulta ou Cabeçalho e informe o nome da consulta ou do cabeçalho e seu valor.

Observação:

Embora seja possível 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 em um web browser ou aplicativo móvel, já definiu 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 de Conector REST.

Você pode adicionar quantos parâmetros à regra desejar, 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 ao qual a regra será aplicada. O valor de URL base é o que você inseriu na etapa de configuraçã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 somente ao nível de recurso especificado no URL Remoto.
(Opcional) Cancele a seleção dos métodos HTTP que você não deseja aplicar às regras que você 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 que conflita com outra, a primeira regra aplicada terá precedência e a regra conflitante será ignorada.

Quando tiver concluído, 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 acima da seção Parâmetros Padrão . Por exemplo, digamos que os seguintes valores foram 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 para 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 tiver sido criada, a descrição será lida:

Para TODOS os METHODS para 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 mapeia para o serviço existente. Usando nosso exemplo:

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

Configurar Políticas de Segurança e Substituir Propriedades

Antes de finalizar a API do conector, você deve considerar como tratar 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 descreve o esquema de autenticação do serviço ao qual você está se conectando é a abordagem recomendada.

Cada política de segurança tem propriedades, chamadas de 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 da 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 a API do conector. Uma descrição de uma política selecionada é exibida abaixo da lista.
Especificar substituições, se aplicável, para a política selecionada, se você não quiser usar os valores padrão.
Para substituir uma propriedade, informe ou selecione um valor diferente do padrão.
Clique em Salvar para salvar seu trabalho ou Salvar e Fechar para salvar seu trabalho e sair do assistente da API do REST Connector.
Clique em Próximo ( > ) para ir para a próxima etapa.