Screenshot 2014-03-07 22.14.43

Tutorial: Integrate your Corona SDK app with any API – part 2

I’ve uploaded the source code for this tutorial to Github in its entirety; you can find it here.

So far, we have found an API at comicvine.com that will allow us to create a cool Superheroine app using Corona SDK. We took a look at its documentation, checked for any blockers like request limits and bad documentation, and decided that it would meet our business requirements. So then we created an account on comicvine.com and grabbed an API key. Now, let’s create the UI for our app. In the final part of our series, we’ll create a module that can be reused for other projects.

So, download the github project I referenced above and follow along. The app will run out of the box in the Corona simulator if have an api key and you want to see how it looks. Let’s create the UI for a trading card app that will display a dataset of interesting female characters in a card interface. Click a card, get a new heroine. The home page will be a card that will display a picture of Wonder Woman (because she’s my favorite!)

Screenshot 2014-03-07 22.14.43

In your main.lua file, we’re only going to have a few lines. We have our API key as a global variable because it needs to be passed through to the module we’ll create in the next tutorial.

APIKEY = ‘my_comic_vine_api_key’

Now, in home.lua, you’re going to build the trading card interface. The first part of that file is all about getting data from comicvine. About line 95, we start building cards. They are just a rounded rectangle with some welcome text. We put an event listener on the card so that if you click it, we start interfacing with the data loaded in the module. That event listener is the moveCard function. Notice that there are a couple of transitions in the moveCard function. One of them rotates the color of the card as you click:

--get the size of the dataset
 
local len = #heroines
 
--create r, g, and b variables that randomize a number so that we can get new rgb colors
 
local r = math.random(len)
local g = math.random(len)
local b = math.random(len)
 
--in the transition, embed a function to flip the color to a new one
 
transition.to(card, {x = -900, time = 400, onComplete = function() card.x = display.contentWidth/2; card:setFillColor(r/255,g/255,b/255) end})

Now, let’s take a look at setting up our module, which is the real meat of this project. This file will be called mod.lua and although it is set up specifically to interface with comic vine, you should be able to use it easily enough for any api integration.

Creating a module is basically creating a series of reusable tables. The first one called Mod is where you are going to store some variables and your functions. It also includes a reference to an important helper file: inspect.lua

Whenever you have to deal with tables, xml, or json data, make sure to include inspect.lua in your project and print out anything you need to inspect like this:

print(inspect(myData))

I had to dig a little in the comicvine forums to find the endpoint of the API, but once you find it, add that to the variables at the top of mod.lua. Some APIs in addition will have both app_id and api_key, as well as fancy headers, but comic vine is pretty simple.

endpoint = “http://beta.comicvine.com/api/”,

Looking at mod.lua, you can see that we have four functions available. One is an init function, one is an onResponse function, and there are two functions that interact with the API, Mod:characters and Mod:character. Structure your API calls to meet your own business requirements while trying to maintain flexibility. Each of those functions bring in two parameters from their external calls, a filter and a callback. Inside those functions we call Mod:onResponse which will grab the data passed from the API and send it back to your app files, via the callback that is specified.

So, to call your module, you first initialize it in main.lua:

mod = require( "Mod" )
mod:init( { apikey = APIKEY } )

and in home.lua you start calling the functions that you specify in the module.

For example, we want to get a dataset of all female characters in the comic vine api, so we call mod.lua like this:

mod:characters("Female",onComplete)

We are passing through the filter “Female” as a data filter, and telling the module what callback will expect the data that comes through.

In the final part of this tutorial, I’ll discuss handling the data that comes through from an API.

6 comments

  1. thanks Jen – looking forward to seeing the next part re responses and how you handle things like the response not coming back within a certain amount of time etc… Perhaps this is a little off topic but not sure if you have any learnings in terms of how to manage “success” if you did starting using something like Parse? e.g. free for the first X/hits/month but what happens if your app is really successful :) Mainly thinking about a freemium app that perhaps does really well re downloads but wasn’t monetizing well.

    1. hi, I recommend using a spinner to handle network requests as can be seen in the mod.lua file. You could beef that up to test for a response within 4 seconds or something, and if you have a problem, pop an alert. Regarding success…in my experience, Parse has a pretty high threshold before you start getting charges. What I am doing with my Roomalyzr app, which is a freemium app, is to basically charge for API access. If they pay IAP, they have the privilege of uploading a photo and calling cloud code to email it out. Otherwise…no pay, no Parse! :)

  2. ok, I see what you mean. So potentially for a freemium game it could be pay (IAP) if you want to add turn based play. Are you just charging a one-off-IAP cost, and then they can upload as much as they want? or are you trying to match the IAP charge against how much they use the API somehow?

    1. For the Roomalyzr (not a game but a biz/utility app, so kind of a different beast) I charge a one-off, because that’s all I think I can get away with :). It would be nice to be able to scale this app but I’m not quite sure how and I know there is competition for it so not putting massive effort there…games of course are different and you can charge for packets as you go.

Leave a Reply