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

Ao desenvolver uma aplicação móvel, você normalmente começa com a camada da interface do usuário primeiro e, em seguida, conecta sua aplicação a outra usando Web services do REST. Essa abordagem funciona bem para aplicativos pequenos ou simples. Quando as aplicações são maiores, e você quer se conectar com vários serviços de back-end, é possível introduzir inadvertidamente problemas de desempenho e segurança.

É uma prática recomendada iniciar a criação de uma camada de API esmaecida entre os serviços de backend 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 chamada única para a camada de API mais completa que trata as chamadas para outros serviços do REST e consolida todos os dados recebidos em uma única resposta para 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 crux de uma API. Ela 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 quase 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 iniciar.
Clique em Novo Recurso e adicione algumas informações básicas.

Cada vez que você clicar em Novo Recurso, criará 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 no X para excluir um recurso.

Observação:
Ver os ícones sob os links Métodos? Cada vez que você define um método para um recurso, um ícone desse recurso aparece no link Métodos. Use-as 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.
Informe 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 para 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 desse 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 o clutter para localizar um recurso de forma mais rápida alternando para o Modo Compacto (à 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. Após pelo menos dois métodos serem 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 passados com cada método.
  O nome do parâmetro é exibido.
2. Forneça um nome para exibição do parâmetro e 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.

Após selecionar um método, ele não será mais listado na lista de métodos, pois você só usa um método 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 definido é exibido na parte superior da página. Clique em um ícone do método para ir diretamente para sua definição.
(Opcional) Insira 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 todas as características a serem aplicadas ao método.

Se você não tiver qualquer transação de recurso definida, clique em Pontos Finais para voltar à página Recursos principais e clique no link Traits para definir um. As transações permitem que você defina um conjunto de operações semelhantes.

Após definir os métodos para o recurso, você poderá definir as solicitações e respostas para esses métodos.

Definir uma Solicitação para o Método

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

Clique em Solicitar 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ê 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 utiliza 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, será necessário 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 será necessário enviar um corpo de método para que não seja necessário especificar um tipo de mídia.
1. Selecione o tipo de mídia para o corpo do seu método, ou seja, o formato da mensagem que você está enviando, como texto, imagens ou forms Web.
  Dependendo do tipo (por exemplo, você não pode inserir um esquema para um tipo de imagem), tem a opção de adicionar um esquema ou um exemplo, ou ambos.
  Ao definir um esquema, adicione apenas os dados necessários à finalidade do recurso. Ou seja, não adicione dados desnecessários que só diminuem a transmissão e aumentarão potencialmente o potencial de erros.
2. (Opcional) Clique em Esquema e insira 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 simulado para o método. Usando os dados simulados pode ajudá-lo a verificar o comportamento dos seus métodos. O exemplo mostra valores simulados para os dados 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, você pode ou não precisar 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 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.
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.
- 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 o uso do API para entender o motivo de um erro potencial na API que você está configurando, use um código de status HTTP para retornar um 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 para exibição do 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, da mesma forma que faria para 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 somente dados pertinentes ao corpo da resposta. Não inclua mais dados do que realmente necessário para a operação.
2. Clique em Exemplo para adicionar dados simulados (no formato JSON) ao corpo da sua resposta. Use os dados simulados para verificar o comportamento dos seus métodos antes de testar com dados reais.
3. Para o tipo de mídia baseado em formulário (por exemplo, multipart/form-data), clique em Adicionar Parâmetro e selecione Obrigatório se o parâmetro for obrigatório. Em seguida, informe um nome e selecione um tipo de valor. Opcionalmente, você pode dar um nome ao seu parâmetro.
4. Para um tipo de mídia baseado em imagem (por exemplo, image/png), você não precisa fazer nada porque não há esquemas ou atributos para fornecer.

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 de Recursos principais. 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 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 REST Connector para criar, configurar e testar sua API de conector.

Para obter uma API básica do conector de trabalho, você pode fornecer o menor nome da API do 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 personalizada para permitir que seus aplicativos chamem as APIs do conector e gerem a API e 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 preenchendo as duas primeiras páginas do assistente da API do REST Connector.

Clique em e selecione Desenvolvimento e, em seguida, APIs no menu lateral.
Clique em REST (se essa for a primeira API de conector a ser criada) ou Novo Conector e, na lista drop-down, selecione REST.
Identifique sua nova API de conector REST fornecendo o seguinte:
1. Nome de 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 seu 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 esta 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 em 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) necessário para conexão com o URL remoto. Um valor 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 atribuição de administrador de nuvem móvel além da sua atribuição de desenvolvedor de serviços, poderá abrir o arquivo policies.properties para ver o valor das políticas de rede para o ambiente atual na view do Administrador. Caso contrário, peça ao administrador do Mobile Cloud para os valores.
Clique em Descritor e especifique as informações de conexão do serviço.

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

Observação:
Somente 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 chamadas de teste para o serviço.

Nessa página, você pode configurar ainda mais o conector das seguintes formas:

(Se você forneceu um descritor na página Descritor) ir para a página Recursos e selecionar os métodos para os recursos expostos.
Defina regras.
Defina políticas de segurança.

Para ter certeza de que a configuração da API do conector é válida, você deve testá-la completamente (não apenas da 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

Você define regras para definir as interações entre seu aplicativo móvel e um serviço. As regras fornecem uma forma de adicionar valores de parâmetro padrão para todas as chamadas de 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 a sintaxe consistente da string do URL, salva o desenvolvedor de código personalizado de ter que inserir esses valores e permite rastrear as diferentes chamadas por meio da 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 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 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 de Conector REST. Da mesma forma, a definição do formato do corpo de 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 quiser, 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 para a regra a ser aplicada. O valor do URL base é o que você informou na etapa de definição de informações básicas e não pode ser editado.
Selecione Não aplicar aos 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 que conflita com outra, a primeira regra aplicada terá precedência e a regra conflitante 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 acima da seção Parâmetros Padrão. Por exemplo, vamos dizer 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 lida da seguinte maneira:

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

Se nenhuma regra tiver sido criada, a descrição será lida:

Para ALL 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 Sobrepor 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. Selecionar 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 podem ser configuradas. Um motivo para substituir uma propriedade de configuração de política é limitar o número de políticas que você tem para manter: em vez de criar várias políticas com configurações um pouco 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 política para a API do seu 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 em 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.