Integrando APIs com o XDK - App de exemplo Hotwire

O código fonte deste exemplo pode ser encontrado aqui: https://github.com/gomobile/sample-masheryhotwire ou faça o download do Intel(R) XDK para acessar outros exemplos de HTML5.

Esta é uma app simples de uma única página criada com o Intel XDK. Ela serve de exemplo de como é simples construir uma aplicação móvel que se integra a uma API externa de serviços WEB. Ela foi construída do zero, usando a opção Start with a Blank Project. Existem muitos outros exemplos na galeria que mostram as interfaces de criação de projetos App Starter e App Designer.

Começando do zero

Enquanto os wizards e o as ferramentas de auxilio de criação de layouts no XDK são extremamente úteis, algumas vezes você quer ir direto para a codificação. Quando você quer ajustar seus scripts e aplicar pixel-pushing com CSS, é do editor de código fonte que você vai precisar para fazer com que sua app se comporte exatamente como você deseja.

Para iniciar a criação de uma app do zero, sem ajuda de nenhuma IDE, simplesmente navegue até a aba Projects no topo da janela do XDK. Clique em Start a New Project na parte de baixo da tela. Na página New Project Setup você deverá informar o nome e o diretório onde quer armazenar o seu projeto. Criado o projeto, você terá um diretório com um único arquivo - index.html. Este é exatamente o modo pelo qual iniciamos este aplicativo.

Layout do projeto: App Framework e a UI

Escolhemos usar o App Framework da Intel como nossa biblioteca JS. Você pode fazer o download do App Framework direto do GitHub https://github.com/01org/appframework/. Usamos ele para as seguintes tarefas:

  • UI - excelentes temas de estilos CSS para iOS, iOS7, Android, Windows 8 e mais
  • Query selector - navegação facilitada pelo DOM para selecionar e modificar valores (muito similar ao jQuery)

Nesta app de exemplo, nós importamos os arquivos base (veja o diretório /js), junto com alguns arquivos CSS (veja a pasta /css), e um plugin (veja a pasta /plugins). Também adicionamos alguns outros arquivos, que serão explicados abaixo.

  • js/
    • appframework.min.us - versão minimizada do framework principal (parte do App Framework)
    • appframework.ui.min.js - versão minimizada do framework de UI (parte do App Framework)
    • api.js - funções para fazer as chamadas remotas de API e fazer o parsing dos resultados (desenvolvidas para esta app de exemplo)
  • plugins/
    • af.8tiles.js - plugin para smartphones Windows 8 (parte do App Framework)
  • css/
    • af.ui.css - elementos gerais da UI (parte do App Framework)
    • icons.css - elementos de fonte e ícones (parte do App Framework)
    • mashery.css - customizações de CSS (desenvolvidas para esta app de exemplo)

Configurando a API Hotwire

O foco principal desta app é demonstrar como fazer chamadas de API, parsing e integração dos dados à view. Neste exemplo, estamos utilizando a API Hotwire, que apresenta os dados que você encontra no site de viagens Hotwire. Para que este exemplo opere de forma adequada, você precisa obter a sua própria chave da API da Hotwire. Esta API é de utilização gratuita e solicitar uma chave para ela leva um minuto ou dois.

Navegue até o portal de desenvolvedores do Hotwire http://developer.hotwire.com. Se você já tiver um Mashery ID, faça o login com as suas credenciais. Se não tiver, complete o registro para criar uma nova conta. Depois de fornecer suas informações de registro e verificar o seu endereço de e-mail, faça o login e solicite uma nova chave (ou cria uma nova aplicação). Você receberá em breve uma chave para a Hotwire Public API – Deals and Shopping APIs na tela do seu navegador e na sua conta de e-mail.

Com esta app de exemplo aberta no XDK, navegue até a aba Develop. Do lado esquerdo do XDK, você irá encontrar uma lista de diretórios e arquivos. Dentro do diretório js, você irá encontrar o arquivo api.js. Selecione e abra o arquivo no editor. Depois, copie a sua nova chave da API (cuidado com os espaços em branco) do seu navegador ou da sua conta de e-mail, e cole no arquivo api.js.

// ********************SET YOUR API KEY HERE*******************
// Insert your Hotwire API Key here. README for more info.
   var apiKey = 'COLOQUE-SUA-CHAVE-DE-API-AQUI';
// ************************************************************

See the Pen Integrating APIs with XDK - Hotwire Sample App - Sample 1 by Intel IDZ (@intelidz) on CodePen.

Uma página, dois painéis

Esta app de exemplo consiste de uma view, renderizada do arquivo index.html. Todos os arquivos de biblioteca mencionados anteriormente são carregados por esta página. O conteúdo é dividido em duas divs - uma com o id de "home" e outra com o id "search-results". O painel de visualização padrão é a div "home", porque ela está declarada como "selected".

<div class="panel" title="Hotwire Demo" id="home" selected="selected" data-footer="none">
  <div class="grid">

See the Pen Integrating APIs with XDK - Hotwire Sample App - Sample 2 by Intel IDZ (@intelidz) on CodePen.

O segundo painel (div id “search-results”) contém dois elementos div filhos. O segundo, “hotwire-results-output” é onde os resultados de busca parseados da API serão colocados.

Fluxo da app: busca e resultados

O fluxo desta app é muito simples. O usuário digita um código de CEP, toca no botão Search Hotwire, e então uma lista de ofertas de hotéis será apresentada na página seguinte. Na página de resultados, o usuário pode clicar no botão Back (navega de volta para a div 'home'), ou clicar em um resultado, que será aberto em uma nova página do navegador. Esta transição de tela da "home" para a "search-results" é feita no arquivo api.js:

// Transição para o painet 'search-results'
// Docs: http://app-framework-software.intel.com/api2/index.html#$_ui_loadContent
   $.ui.loadContent("#search-results", false, false, "slide");

See the Pen Integrating APIs with XDK - Hotwire Sample App - Sample 3 by Intel IDZ (@intelidz) on CodePen.

Fazendo a chamada, parseando os resultados

A função searchDeals() no arquivo api.js é onde a chamada da API é iniciada. a url para o método Hotwire Hotel Deals é preparada, com a chave de API e o CEP concatenados. A chamada é feita através da seguinte declaração:

var apiCall = $.get(url, function(data) {
  searchDealsCallback(data);
});

See the Pen Integrating APIs with XDK - Hotwire Sample App - Sample 4 by Intel IDZ (@intelidz) on CodePen.

$.get é uma função da App Framework, similar a função GET do jQuery. A chamada é assíncrona. Se tiver sucesso, ela irá chamar searchDealsCallback. Esta é a função que realiza o parse, acrescenta a lista de links ao DOM e faz a transição para o outro elemento div.

Os resultados retornam em JSON. Utilizando a função $.parseJSON() a iteração através dos resultados é bem fácil. Um dos elementos raiz do objeto de resultados é uma array chamada Result[].

{
  "Result": [
    {
      "Headline": "San Francisco 4 Star Hotel, $99/night",
      "Url": "http://www.hotwire.com/hotel/...",
      ...
    },
    {
      "Headline": "San Francisco 4 Star Hotel, $105/night",
      "Url": "http://www.hotwire.com/hotel/...",
      ...
    }
  ]
}

See the Pen Integrating APIs with XDK - Hotwire Sample App - Sample 5 by Intel IDZ (@intelidz) on CodePen.

O código para realizar o parse no conjunto de resultados é este:

var data = $.parseJSON(payload);
for (var x in data.Result) {
  var deal = data.Result[x];
  // Use deal.Url and deal.Headline
}

See the Pen Integrating APIs with XDK - Hotwire Sample App - Sample 6 by Intel IDZ (@intelidz) on CodePen.

Resumo

A integração de APIs RESTful em sua app é bem direta usando o App Framework. Tudo o que você precisa é entender o método da API, sua mecânica e sua estrutura de payload. Este é apenas um pequeno exemplo de uma grande série de exemplos que demonstram integração de APIs. Para descobrir outras APIs RESTfull para a criação da sua app, visite http://developer.mashery.com/apis.