Introduction to RestKit Tutorial

Update 02/24/2014: Updated RestKit tutorial for new version of the RestKit library.

There are a lot of web services that you can connect to to get interesting and useful data.

For example, Twitter has a web service you can use to list and send Tweets, and Foursquare has a web service you can connect to that allows you to retrieve a list of restaurants near your current location.

If you want to use these APIs, you can connect to them directly with NSURLRequest or a wrapper library like AFNetworking. However, there’s an easier way for many of these APIs – use RestKit!

RestKit is a popular and easy-to-use framework that saves you from having to write much of the boring code you usually have to when working with web service APIs, such as parsing JSON or mapping responses to objects.

In this RestKit tutorial, we’ll try it out with by making a simple app that uses the FourSquare API to list the coffee shops nearby – because we all love and need our coffee! :]

This tutorial is for any level of iOS developer, from beginner to advanced. So read on and get ready for a RESTful caffeine buzz! If you are not sure about networking in general on iOS yet, the I suggest checking out some of the other tutorials on this site

Getting Started

To start, we’re going to create a Master-View application in Xcode. If you’re already familiar with how to do this and how it works, feel free to glance through this quickly and move to the next section – but I’m going to include some more details for the beginners.

Start up Xcode and create a new project with the iOS\Application\Master-Detail Application template.

Enter CoffeeKit for the product name, set device family to iPhone (leave “Use Core Data” checkbox unchecked):

Click Next and choose a location to save your project.

The Master-Disciple, er, wait… Master-Detail template is a fully-functioning app, so build and run.

You should see a blank screen with Edit and Add (+) buttons. Click the (+) button to add some table entries to the Master screen. Tapping one of these entries will show a Detail screen:

You can see how this format is perfect for lists of data that contain different levels of information. Open MasterViewController.h. You will see something like this:

#import <UIKit/UIKit.h>

@interface MasterViewController : UITableViewController

@end

MasterViewController is a UITableViewController, which manages a UITableView and conforms to two protocols: UITableViewDelegate and UITableViewDataSource. UITableViewDataSource handles the data model needs for the UITableView, and UITableViewDelegate handles the appearance needs of the UITableView (such as managing selections; configuring section headers and footers; deleting and reordering of cells).

Look at some key methods in MasterViewController.m:

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView 
{ 
    return 1; 
}

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section 
{
    return _objects.count; 
}

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath*)indexPath 
{ 
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"Cell" forIndexPath:indexPath];

    NSDate *object = [_objects objectAtIndex:indexPath.row];
    cell.textLabel.text = [object description];
    return cell; 
}

The first two methods, numberOfSectionsInTableView: and tableView:numberOfRowsInSection: are as their names imply. You use them to tell the table how many sections it has and how many rows are in each section.

You specify the data displayed in each cell using tableView:cellForRowAtIndexPath:.

For this tutorial, you’ll only be using the Master View Controller to display a list of nearby coffee shops. To keep things simple, the Detail View Controller will not be used. So remove the following:

• prepareForSegue:sender: from MasterViewController.m
• The #import for DetailViewController.h at the top of MasterViewController.m.
• The files DetailViewController.h and DetailViewController.m. (Make sure you choose Move to trash – you really don’t need these any more!)

Next, delete “Detail View Controller – Detail” from Main.storyboard. Yes that’s right, the entire view controller! You can find it here:

RESTing Easy

OK now on to the fun stuff – RestKit!

The RestKit GitHub project describes RestKit as the following:

RestKit is a modern Objective-C framework for implementing RESTful web services clients on iOS and Mac OS X. It provides a powerful object mapping engine that seamlessly integrates with Core Data and a simple set of networking primitives for mapping HTTP requests and responses built on top of AFNetworking. It has an elegant, carefully designed set of APIs that make accessing and modeling RESTful resources feel almost magical.

…like unicorns.

RestKit has three main components:

1. Network – RestKit now uses AFNetworking v1.3.3 for the network layer. RestKit maintainers are working on updating to AFNetworking 2.0.
2. Object Mapping – Provides a simple API for turning remote JSON/XML responses into local objects.
3. Core Data – Provides additional support on top of the object mapper for mapping remote resources to persisted local objects. (No Core Data for this tutorial)

In other words, that’s all a lot of code that you don’t have to write! ;]

The hardest thing about working with RestKit is the installation and setup. There are two setup options: CocoaPods (with automatic configuration, i.e. the easy way) or Git submodule (with manual configuration, the harder way). I recommend using CocoaPods.

Open up Terminal and enter the following commands:

Install RestKit into your project:

Close your CoffeeKit.xcodeproj and reopen CoffeeKit.xcworkspace.

Open up Terminal and enter the following commands:

Next, add RestKit to your project. In a Finder window, open the RestKit folder inside your CoffeeKit project folder. Drag RestKit.xcodeproj into the Project Navigator in Xcode, like this:

Now that you’ve told your project RestKit is there, it’s time for the most detailed step: configuring Restkit so you can use it properly. You’ll both configure settings and add some frameworks to your build configuration.

Click Add one last time!

1. The first option is using CocoaPods: [for more on CocoaPods, see Introduction to CocoaPods.]

   Open up Terminal and enter the following commands:

   $ sudo gem install cocoapods
   $ pod setup
   $ cd /path/to/CoffeeKit
   $ touch Podfile
   $ [edit] Podfile (using your preferred editor; vim, nano, etc)
   platform :ios, '5.0'
   pod 'RestKit', '~> 0.20.0'
   

   Install RestKit into your project:

   $ pod install
   

   Close your CoffeeKit.xcodeproj and reopen CoffeeKit.xcworkspace.

2. The second option is as a Git submodule:

   Open up Terminal and enter the following commands:

   $ cd /path/to/CoffeeKit
   $ git init 
   $ git submodule add git://github.com/RestKit/RestKit.git RestKit
   $ git submodule update --init --recursive
   

   Next, add RestKit to your project. In a Finder window, open the RestKit folder inside your CoffeeKit project folder. Drag RestKit.xcodeproj into the Project Navigator in Xcode, like this:

   

   Now that you’ve told your project RestKit is there, it’s time for the most detailed step: configuring Restkit so you can use it properly. You’ll both configure settings and add some frameworks to your build configuration.

   1. Click on the top item in the Project Navigator pane and select the CoffeeKit target.
   2. Click the Build Settings filter for Other Linker Flags in the search box. Click the value column to the right of Other Linker Flags, add -ObjC and hit return.

      

   3. Now clear the search box text and input Header Search Paths. Double click the value column to the right of Header Search Paths, add "$(BUILT_PRODUCTS_DIR)/../../Headers" to the list (be sure to include the quotes) and hit return. Then click outside the drop down to return to the build settings.

      

   4. Now click on the Build Phases tab, click on the disclosure triangle for Target Dependencies, and tap the Add (+) button. Select RestKit and click Add.
   5. Now click on the Link Binary With Libraries disclosure triangle and tap the Add (+) button. Select libRestKit.a and click Add.
   6. You also need to add some required Apple frameworks. Click the Add (+) button again and select the following: (⌘-click for multi-select)

      

      • CFNetwork.framework
      • CoreData.framework
      • MobileCoreServices.framework
      • Security.framework
      • SystemConfiguration.framework

      Click Add one last time!

   7. Next you need to update the precompiled header file to avoid build warnings from AFNetworking. Open CoffeeKit-Prefix.pch (it’ll be under Supporting Files). Replace the contents with the following:

      #ifndef __IPHONE_5_0
      #warning "This project uses features only available in iOS SDK 5.0 and later."
      #endif
      
      #ifdef __OBJC__
          #import <UIKit/UIKit.h>
          #import <Foundation/Foundation.h>
          #import <SystemConfiguration/SystemConfiguration.h>
          #import <MobileCoreServices/MobileCoreServices.h>
      #endif
      

1. Click on the top item in the Project Navigator pane and select the CoffeeKit target.
2. Click the Build Settings filter for Other Linker Flags in the search box. Click the value column to the right of Other Linker Flags, add -ObjC and hit return.

   

3. Now clear the search box text and input Header Search Paths. Double click the value column to the right of Header Search Paths, add "$(BUILT_PRODUCTS_DIR)/../../Headers" to the list (be sure to include the quotes) and hit return. Then click outside the drop down to return to the build settings.

   

4. Now click on the Build Phases tab, click on the disclosure triangle for Target Dependencies, and tap the Add (+) button. Select RestKit and click Add.
5. Now click on the Link Binary With Libraries disclosure triangle and tap the Add (+) button. Select libRestKit.a and click Add.
6. You also need to add some required Apple frameworks. Click the Add (+) button again and select the following: (⌘-click for multi-select)

   

   • CFNetwork.framework
   • CoreData.framework
   • MobileCoreServices.framework
   • Security.framework
   • SystemConfiguration.framework

   Click Add one last time!

7. Next you need to update the precompiled header file to avoid build warnings from AFNetworking. Open CoffeeKit-Prefix.pch (it’ll be under Supporting Files). Replace the contents with the following:

   #ifndef __IPHONE_5_0
   #warning "This project uses features only available in iOS SDK 5.0 and later."
   #endif
   
   #ifdef __OBJC__
       #import <UIKit/UIKit.h>
       #import <Foundation/Foundation.h>
       #import <SystemConfiguration/SystemConfiguration.h>
       #import <MobileCoreServices/MobileCoreServices.h>
   #endif
   

$ sudo gem install cocoapods
$ pod setup
$ cd /path/to/CoffeeKit
$ touch Podfile
$ [edit] Podfile (using your preferred editor; vim, nano, etc)
platform :ios, '5.0'
pod 'RestKit', '~> 0.20.0'

$ pod install

$ cd /path/to/CoffeeKit
$ git init 
$ git submodule add git://github.com/RestKit/RestKit.git RestKit
$ git submodule update --init --recursive

#ifndef __IPHONE_5_0
#warning "This project uses features only available in iOS SDK 5.0 and later."
#endif

#ifdef __OBJC__
    #import <UIKit/UIKit.h>
    #import <Foundation/Foundation.h>
    #import <SystemConfiguration/SystemConfiguration.h>
    #import <MobileCoreServices/MobileCoreServices.h>
#endif

For the final step in the setup, verify your RestKit installation and configuration. Open AppDelegate.m, and add the following:

 
#import <RestKit/RestKit.h>

Build and run. If it builds without error, RestKit is set up correctly. Feel the force!