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.
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.
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.
- 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étodoGET
, não será necessário enviar um corpo de método para que não seja necessário especificar um tipo de mídia. - 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.
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:
-
Nome de Exibição da API: o nome como ele aparecerá na lista de APIs do conector.
-
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.
-
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 arquivopolicies.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.
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
ePUT
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
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: