Enhancing Titanium: Simplify your API interactions with RESTe collections

You’ve probably done API calls. You probably also made a function around it to save you from writing the xhr parts in your controllers. You might even gone as far as writing a commonjs module to be able to make API calls even easier.

What if I told you, there is no need to reinvent the wheel. For some reason we all tend to keep doing that in Titanium. It is time to Enhance your API experience. I will be giving you an example how I solved it in the iOS App Spoorbaan.

First, lets install RESTe. For this, you really should use Gittio CLI. If you don’t have this installed already on your machine, do so now. To install RESTe using Gittio, go to your root folder of the project in the Terminal and type

gittio install reste

RESTe is now added to your project and you can include it, I would suggest in the file Alloy.js

var api = require(“reste”);

Now, to keep clutter away from Alloy.js, create a lib file with the config

/App Project/App/lib/apiconfig.js

So now go to apiconfig.js, and create the config as defined on the RESTe GitHub page, but for the purpose of simplicity just follow my steps.

First, just add the basic configuration to apiconfig.js. This is just a timeout, and the root URL for the API, in this case, my own (open) Dutch trains API.

exports.config = {
    url: 'http://spoorbaan.com/API/',
    timeout: 10000
};

Now time to apply the config, below the require line in Alloy.js:

api.config(require('apiconfig').config);

Now, we’ll add a method to get departures from a specific train station (add this below the timeout section, within the config object)

methods: [{
    name: 'getDepartures',
    get: 'station/<code>'
}]

To call this endpoint and get the JSON, all you need to do is this:

api.getDepartures({code: 'asd'}, function(departures) {
    // you've got the departures JSON here
    // this will call http://spoorbaan.com/API/station/asd
});

But, you don’t want JSON. You want a collection, which can be done to add a models section to the apiconfig.js file, within the config object:

models: [{
    name: 'departure',
    id: 'id',
    collections: [{
        name: 'departures',
        content: 'times',
        read: 'getDepartures'
     }]
 }]

The section “content: ‘times’” is specifically for this API call, since the array of data is within the object “times” in the response. As you can see in the API call response If your array is in the root, just skip the content part.

When this part of the code is added, it will, under the hood, create a model called “Departure”, and a collection called “Departures”. This means, you’ve got a “Departures” backbone collection around, hooked up to an API you can use like this:

Alloy.Collections.departures.fetch({ });

Yes, you read that right. Just fetch, and voila. And now walk through the collection items and render it on a ListView right?

Wrong! No running through it, everything is automated! But first, we’re finalizing the fetch part because we forgot to put the “code” in.

Alloy.Collections.departures.fetch({
   code: "asd"
});

Now, this code will take care of fetching the API content for us, next we’ll be rendering. First as basic “ListView” with a template

<ListView defaultItemTemplate="departure" id="departureListView">           
    <Templates>
        <ItemTemplate name="departure" class="departureTemplate">
            <Label class="destination" bindId="destination" />
        </ItemTemplate>
    </Templates>
    <ListSection>
    </ListSection>
</ListView>

Now that we have a ListView and a ItemTemplate, we can let the collection generate the ListItems. Note that in this example we’re only just displaying the destination name. But of course, in the app we’ve got much more. But this just for the sake of simplicity.

<ListSection dataCollection="departures">
    <ListItem 
      destination:text="{destinationName}" 
    />
</ListSection>

And that is it! That will render a list of listItems, with the name of the destination from the API.

Well almost. If you had a look at the API data, you might’ve noticed the name of the destination is not in the root of a single departure object. And “destinationName” is not available in the data. So how did it get in the view? Well, I added it through the dataTransform function. So a short edit to our previous code:

<ListSection dataCollection="departures" dataTransform="parseDeparture">
    <ListItem 
      destination:text="{destinationName}" 
    />
</ListSection>

I’m pointing to the function parseDeparture, which is located in the controller. The dataTransform function will receive the model it wants, just before it renders the view. You will need to return a JSON object.

function parseDeparture(model){
    var transform = model.toJSON();
    transform.destinationName = transform.destination.name;
    return transform;
}

So now, with a transform function, you can manipulate data all you like, and pass that back to the view.

Perhaps you ask, why would I do it like this? Easy! First, the code is very neat, and simple. No more need to look after API responses and such. Second, it is very fast! Your view becomes very responsive! And that is always a very big plus.

So try it out, with my API if you like, and enhance your Titanium Experience.

Looking for other guides? Happy to write them on request!

Resources:

• GitTio — Everything Titanium related found on GitHub (Modules & Widgets
• RESTe by Jason Kneen — A simple REST API helper
• Alloy Data Binding guide on Appcelerator.com
• Spoorbaan API by me. You might need this call too