Design & Feature Set

RestKit is a mature library providing a layer between your app’s domain objects and a restful backend in the cloud. It enables you to live in a world of Cocoa objects and then serialize them to and from your backend system with minimum fuss. RestKit aims to stay out of your way and make interacting with the web as simple and painless as possible. RestKit can currently be considered production quality and is in use on GateGuru as well as a number of other Two Toasters apps thriving in the App Store.

It is quickly approaching 1.0, but still has some rough edges and currently lacks sample code to help others get started (rest assured we’ll have sample code ready by next week!). Let’s take a quick tour of the feature-set:

• Simple, clean API designed to be succinct and Cocoa like
• Works on OS X and iPhone OS
• Minimal external dependencies, currently the only external dependency is on json-framework
• Provides robust wrappers for the request/response cycle with MIME type and status code introspection methods (i.e. isOK, isHTML, isJSON, etc.)
• Provides support for synchronous as well as asynchronous requests out of the box
• Supports file uploads and other requests that cannot be URL encoded
• Provides a key-value coding based system for model mapping from JSON payloads to Cocoa object properties
• Allows for model mapping to Core Data backed persistent models or transient vanilla NSObjects
• Can hydrate Core Data relationships as well as properties
• Model mapping operations are threaded to prevent the main UI thread from becoming bogged down while network operations are handled
• Stays focused on providing excellent transport layer support without bringing UI baggage along for the ride
• Allows for easy integration with Three20 by using the RKRequestTTModel and RKRequestFilterableTTModel (the filterable flavor enables support for searching, filtering the loaded models via one or more NSPredicate’s, and sorting the models via an NSSortDescriptor)
• Quick switching between development/staging/production hosts by using a baseURL and resourcePath’s instead of full URL strings
• Just enough support for Rails conventions to make integration easy, while avoiding becoming a Rails-centric library
• Support for a global ‘offline’ mode that enables the use of Core Data as an object cache queried via resourcePath’s. Will not generate requests in offline mode.

Let’s check out some code…

Below are some simple snippets to give you a taste of what it feels like to work with RestKit.

Request/Response cycle

Let’s initialize a RestKit client, fire a GET request, and then ask the RKResponse object to tell us a bit about the results of the request. Note that there are corresponding methods for POST/PUT/DELETE and associated flavors that allow passing in parameters for the request.

#import <RestKit/RestKit.h>

RKClient* client = [RKClient clientWithBaseURL:@"http://myrestkitapp.heroku.com"];
[client isNetworkAvailable];
[client get:@"/airports" delegate:self callback:@selector(airportsDidLoadResponse:)];

- (void)airportsDidLoadResponse:(RKResponse*)response {
 NSString* responseBody = [response bodyAsString];
 if ([response isHTML]) {
 // show HTML page
 } else if ([response isJSON]) {
 // parse JSON
 } else if ([response isRedirect]) {
 // follow the redirect
 }
}

Initialize RestKit model manager

Let’s initialize the a Core Data backing store for RestKit, set the mapping format to JSON (currently the only format supported, though MessagePack is planned), and register some mappings from model classes to payload elements.

RKModelManager* manager = [RKModelManager managerWithBaseURL:@"http://myrestkitapp.heroku.com"];
manager.format = RKMappingFormatJSON;
manager.objectStore = [[RKManagedObjectStore alloc] initWithStoreFilename:@"RestKitApp.sqlite"];

// Establish model mapping relationships from JSON payload elements to Cocoa classes
[manager registerModel:[GGAirport class] forElementNamed:@"airport"];
[manager registerModel:[GGZone class] forElementNamed:@"zone"];

Model Mapping

Here we can see what a mappable object implementation looks like. The elementToPropertyMappings method defines a dictionary specifying how to map elements in the payload to properties of the model. The elements are extracted via valueForKeyPath, so you can traverse through the response using key-value coding instead of relying on direct 1 to 1 mappings from your payload to your models.

@implementation GGAirport

@dynamic city;
@dynamic code;
@dynamic name;
@dynamic state;
@dynamic country;
@dynamic airportId;

+ (NSString*)primaryKey {
 return @"airportId";
}

+ (NSDictionary*)elementToPropertyMappings {
 return [NSDictionary dictionaryWithObjectsAndKeys:
 @"city", @"city",
 @"code", @"code",
 @"name", @"name",
 @"state", @"state",
 @"country", @"country",
 @"airportId", @"id",
 nil];
}

// Sub-models included in the payload and specified here will be model-mapped
// and then assigned as the target for any Core Data associations
+ (NSDictionary*)elementToRelationshipMappings {
 return [NSDictionary dictionaryWithKeysAndObjects:
 @"zone", @"zone",
 nil];
}

@end

Here we see an example of how to work with the manager to load mappable models from the remote system. Unlike the client implementation which is callback based for flexibility, the model loader uses a simple protocol that abstracts successful and failed model loads into two methods.

@implementation GGAirportConsumerExample

- (void)loadAirports {
 [[RKModelManager manager] loadModels:@"/airports" delegate:self];
}

- (void)modelLoaderRequest:(RKRequest*)request didLoadModels:(NSArray*)models response:(RKResponse*)response model:(id<RKModelMappable>)model {
 for (GGAirport* airport in models) {
 NSLog(@"I loaded an airport named %@", airport.name);
 }
}

- (void)modelLoaderRequest:(RKRequest*)request didFailWithError:(NSError*)error response:(RKResponse*)response model:(id<RKModelMappable>)model {
 NSLog(@"**** Model Loader Request failed with error : %@", [error localizedDescription]);
}

@end

Where do we go from here?

I hope I’ve given you enough of a taste of RestKit to get excited and dive in. We’ve set up a Google Group as well as the normal channels of communication:

• Write back in the comments
• Fork us on GitHub: http://github.com/twotoasters/RestKit
• Join the mailing list: http://groups.google.com/group/restkit
• Hit us up on Twitter: http://www.twitter.com/twotoasters

Additional documentation, API polish, and sample code are in the works and on the way. Please let us know what you think and how you are using RestKit.

Running is more fun with friends! Use the FREE RunnersUnite! application from Dick’s Sporting Goods to let your friends know about your runs and invite others to run with you. RunnersUnite! also lets you find popular running spots in your area, and see where people are running near you right now. As an added bonus, users that install the RunnersUnite! application will be able to receive special promotions from Dick’s Sporting Goods on popular running gear. So get out there and run – but don’t run alone!

Sign in with your Facebook, Twitter, or Foursquare account to get started!

365 Incorporated, a leader in sports properties, wanted to allow soccer and rugby fans in the United States to find local venues that are showing broadcasts of their favorite rugby and soccer games. Two Toasters partnered with 365 Inc. to implement their idea through a suite of iPhone applications.

We designed and built both iPhone applications and implemented their supporting web servers. The Where to Watch the Match applications showcase Two Toasters technical ability and diverse skill set to implement for a wide range of clients.

Fake Conversation (http://www.fakeconversation.com/) is a fun app we created in partnership with Dr. Strange App that allows users to receive fake phone conversations that give them prepared scripts so they can pretend to be any number of humorous characters.

The 2.0 update to Fake Conversation that features a marketplace of new conversations that can be purchased using in app purchases.Fake Conversation shows how a fun idea can be turned into a solid revenue stream with good mobile strategy centered around monetization

Regenus, LLC. partnered with Two Toasters to develop one of the highly ranked ideas on MyAppIdea: Cash Register. Cash Register is a simple tool that replaces the need for a physical cash register or point of sale system for events like a garage sale. Cash Register will also optionally perform basic inventory management.

Cash Register features a lightweight custom interface that showcases Two Toasters design abilities. Additionally Cash Register is another case where Two Toasters took an idea, refined it, and implemented a commercially successful mobile application.

The airport is a stressful environment as it is with long security lines and the constant wave of travelers. Now imagine, trying to find a place to eat or buy a last minute gift for a loved one in this maze. Mobility Apps, a leading innovator in the space saw an opportunity to improve the airport experience by creating a mobile guide for airport amenities. We were thrilled to partner with them to take their idea to market, implementing an iPhone application and web backend, to manage the entire ecosystem.

From the get go, the traveler’s experience was central in shaping the design of the application and ensuring that they were able to access information easily. We achieved this by offering a simple interface where the traveler could select the airport, terminal and filter categories to find relevant amenities. The second focus was creating an engaging app to foster an active community of travelers that would fill in details like photos, reviews, flag out-of-date and new amenities to create a self propelling ecosystem. We worked together with Mobility Apps to take the social travel experience further with facebook and twitter integration including contextual posts to share travel with friends and a social leader board to reward content creation.

We are excited to be a part of the GateGuru story and helping travelers change the way they view the airport experience.

As a result, I decided to recreate the iPhone in a completely resizable format for Photoshop. Admittedly it would’ve been smarter to do this in Illustrator, but since most of the time these designs are mocked up in Photoshop it works out well.

Ultimately, the outcome of this little experiment is a combination of quite a few shapes and layer styling that looks extremely realistic.

Some Notes on the File:

• The zip archive contains a psd format of the iPhone.
• The psd can be infinitely resized without a loss in quality as long as you check the “scale styles” property under image resize.
• All of the layers are completely editable–however it is not recommended that you touch any of the shapes within the speaker group or the bezel group.
• The files are published under creative commons and can be used both commercially and personally as long as this post is attributed in some way.

Download

541x1000px PNG (44kb)

Zip Archive with PSD (142kb)