Integrando APIs com o XDK - App de exemplo da Rotten Tomatoes

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

Esta é uma app simples, de uma única página, criada usando o Intel XDK. Ela serve de exemplo de como é fácil construir um app móvel que integre uma API externa na Internet. Ela foi feita do zero, usando o fluxo de desenvolvimento do App Designer. Existem muitos outros exemplos na galeria que mostram as interfaces de criação de projetos App Start e Blank Project.

Usando o App Designer do XDK

Esta app de exemplo foi construída através do App Designer do XDK, que fornece uma interface gráfica de fácil utilização para criar nossas views. Neste caso, nossa view possui uma única página, com um cabeçalho e quatro linhas. Alternar entre design e codificação é bem fácil, com o editor te permitindo fazer os ajustes finos necessários no código que a ferramenta gráfica de construção de UI gera automaticamente.

Layout do projeto: O App Framework e a UI

Escolhemos usar a biblioteca App Framework da Intel. Você pode fazer o download da App Framework direto do Github https://github.com/01org/appframework/. Nós a utilizamos nas 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 básicos (veja o diretório /js), junto com alguns arquivos CSS (veja /css) e um plugin (veja /plugins). Nós também adicionamos alguns outros arquivos que sã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 Rotten Tomatoes

O foco principal desta app é demonstrar como fazer chamadas de API, parsear os dados e integrar estes dados na view. Neste exemplo, estamos usando a API Rotten Tomatoes, que apresenta dados que serão encontrados no site de review de filmes Rotten Tomatoes (nota, imagens, título, etc.). Para que este exemplo funcione de forma apropriada, você vai precisar da sua própria chave da API Rotten Tomatoes. Esta API é de utilização livre e obter uma chave para a API toma apenas um ou dois minutos.

Vá até o portal para desenvolvedores do Rotten Tomatoes - http://developer.rottentomatoes.com. Se você já tiver um Mashery ID, utilize-o para o login. Se não, registre uma nova conta. Depois de fornecer os suas informações de registro, verifique o seu endereço de e-mail, faça o login e solicite uma chave (ou crie uma nova aplicação). Você receberá em breve uma chave de API para a API Rotten Tomatoes no seu navegador e via e-mail.

Com esta aplicação de exemplo aberta no XDK, navegue até a aba Develop. No 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/abra o arquivo dentro do editor e depois, copie sua nova chave da API (cuidado com os espaços em branco) da sua outra janela do navegador ou de seu e-mail para o arquivo api.js.

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

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

Uma página, quatro linhas

Esta app de exemplo foi desenvolvida com uma view, renderizada do arquivo index.html. Todas as bibliotecas mencionadas anteriormente são carregadas à partir desta página. O conteúdo é dividido em quatro linhas. As três primeiras linhas são compostas por conteúdo estático. A quarta linha contém um elemento div que iremos utilizar para popular com os dados obtidos do Rotten Tomatoes.

<div id="home" selected="rotten tomatoes-results-output">
</div>

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

Fluxo da app: Busca e resultados

O usuário clica em Opening Movies ou em Top DVD Rentals. Cada botão dispara uma função diferente em api.js que é responsável por fazer as chamadas adequadas da API. O div citado anteriormente é esvaziado, populado com um cabeçalho e com os resultados parseados.

Vamos dar uma olhada na função fetchTopRentals() em api.js, onde a chamada da API é iniciada. A url para o método da Rotten Tomatoes é preparada com a chave da API concatenada. A chamada é feita através da seguinte declaração:

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

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

$.get é uma função da App Framework, similar às funções GET do jQuery. A chamada é assíncrona. Em caso de sucesso, ela irá chamar fetchTopRentalsCallback. Esta é a função que executa o parse e adiciona a lista de thumbnails e links ao DOM.

Os resultados são retornados em JSON. Utilizando a função $.parseJSON(), a iteração pelos resultados é bem simplificada. Um dos elementos raiz do objeto de resultados é um array chamado movies[].

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

var data = $.parseJSON(payload);
var movies = data.movies;
$.each(movies, function(index, movie) {
  // Verificar movie.ratings.critic_rating para ver se o filme é 's 'Rotten' ou 'Fresh'
  // Use movie.links.alternate e movie.title para a URL e o título do filme
}

See the Pen Integrating APIs with XDK - Rotten Tomatoes Sample App - Sample 4 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.