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.