API for iOS app - part 1

And here we go, with out firts technical post.

One of the problems we, as mobile developers, have to face in almost any mid-to-high complexity project, is integrating our app with a backend. To solve this issue, the market offers today many BaaS solutions. Just to name a few platforms that offer an iOS SDK that could be easily integrated (disclaimer: I’m not endorsing anyone or suggesting that the following are better than others):

Of course there are as many advantages as drawbacks in opting for such a service. On the one side there’s the ease of use of APIs to retrieve and parse objects you need to store on those backends. On the other side you’re tying your app to a specific service and you’re exposing yourself to higher expenses (BaaS generally offer free plans for quite small applications, but if you’re going to scale then you’ll need to share your revenues not only with Apple).

The approach I favored in my last projects is somewhat mixed. I now tend to outsource some of the more difficult stuff (like user management, which requires setting up the whole signup process) and insource the development of very simple APIs.

I’ve been personally using Stackmob and Appcelerator backends for a couple of months. I admit they have some quite useful features, but let’s say you just need some kind of web platform (a stripped down CMS?) where you (or your clients) could input and update some basic informations. A typical example could be a product catalog: entries in the online database represent goods, where each good is associated to a category. And you just need to add, update or delete items so that your catalog is always up-to-date. This is the optimal situation where a custom, self-developed backend could make your day.

I will now guide you step by step in the process of creating and stubbing a very simple RESTful webservice made with Ruby on Rails (RoR or Rails for short). In a later post I’ll talk about how to consume this webservice with an iOS application. Let’s get our hands dirty!

Installing necessary software

First thing first: grab a copy of Git and install it on your Mac (current stable release at the time of this writing 1.8.0.2).

You’ll then need to install (or update) Ruby on your Mac. I suggest you use rvm: it’ll help you manage Ruby versions and gems (there’s even a GUI for Mac OS X - JewelryBox). There’s plenty of documentation here. Basically, from your Terminal, run the folloing command:

$ \curl -L https://get.rvm.io | bash -s stable --ruby

The above command will install both RVM and the latest version of Ruby. Then install the latest version of Ruby (1.9.3 as of this post):

rvm install 1.9.3  

And use the newly installed Ruby:

rvm use 1.9.3  

If you now run

ruby --version  

you should see something like this:

ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-darwin11.4.0]  

Almost done... To install rails, just type:

gem install rails  

That’s it! Now we’re good to go.

Set up your first RoR project

Now from the terminal navigate (cd) into a directory where you’ll want to store the Rails project and type:

rails new my-first-api  

Rails will generate a whole bunch of files. I’m not going to cover here what all those files do (you can find plenty of informations online - you could start here if you wanna learn more), but keep in mind that Rails was built with a convention over configuration philosophy and that therefore the command you just ran basically set up for you a fully functional application. In fact, if you cd (cd my-first-api) in the previously generated directory and run in the terminal:

rails server  

you can start a local server to serve web pages on your machine. If you’ll now visit http://localhost:3000/ you should see the standard Rails welcome page. Congrats, you’ve just built your first RoR app!

Create a basic API

Now it’s time to setup a very basic API that you’ll use to populate a product table (later we’ll retrieve those products as JSON). If you’re still running you server (the one you started before with rails server, you can now shut it down by pressing ctrl-c.

Let’s keep things simple: products, for the time being, will be represented only by their name (in a future post I’ll show you how to add associations, a category for example).

So, type in the terminal:

rails generate scaffold Product name:string  

The command you just ran made Rails create all the files needed (Model, Views and Controller - MVC) to respond to standard RESTful actions. Now you’ll need to generate the corresponding database tables (by default Rails uses SQLite in a development environment):

rake db:migrate  

Let’s start the server again (you can just type rails s) and visit http://localhost:3000/products. You should now be able to add, update and delete your products! The site is not very pretty, but it’s fully functional. You can already retrieve your objects in JSON format by visiting http://localhost:3000/products.json. Cool, huh?

In the next part I’ll show you how to easily implement a RESTful compliant iOS app to consume the webservice we just created.