Overview

The RKObjectManager class provides a centralized interface for performing object mapping based HTTP request and response operations. It encapsulates common configuration such as request/response descriptors and routing, provides for the creation of NSURLRequest and RKObjectRequestOperation objects, and one-line methods to enqueue object request operations for the basic HTTP request methods (GET, POST, PUT, DELETE, etc).

Object Request Operations

Object request operations model the lifecycle of an object mapped HTTP request from start to finish. They are initialized with a fully configured NSURLRequest object and a set of RKResponseDescriptor objects that specify how an HTTP response is to be mapped into local domain objects. Object request operations may be constructed as standalone objects, but are often constructed through an RKObjectManager object. The object request operation encapsulates the functionality of two underlying operations that perform the bulk of the work. The HTTP request and response loading is handled by an RKHTTPRequestOperation, which is responsible for the HTTP transport details. Once a response has been successfully loaded, the object request operation starts an RKResponseMapperOperation that is responsible for handling the mapping of the response body. When working with Core Data, the RKManagedObjectRequestOperation class is used. The object manager encapsulates the Core Data configuration details and provides an interface that will return the appropriate object request operation for a request through the appropriateObjectRequestOperationWithObject:method:path:parameters: method.

Base URL, Relative Paths and Path Patterns

Each object manager is configured with a base URL that defines the URL that all request sent through the manager will be relative to. The base URL is configured directly through the managerWithBaseURL: method or is inherited from an AFNetworking AFHTTPClient object if the manager is initialized via the initWithHTTPClient: method. The base URL can point directly at the root of a URL or may include a path.

Many of the methods of the object manager accept a path argument, either directly or in the form of a path pattern. Whenever a path is provided to the object manager directly, as part of a request or response descriptor (see “Request and Response Descriptors”), or via a route (see the “Routing” section), the path is used to construct an NSURL object with [NSURL URLWithString:relativeToURL:]. The rules for the evaluation of a relative URL can at times be surprising and many configuration errors result from incorrectly configuring the baseURL and relative paths thereof. For reference, here are some examples borrowed from the AFNetworking documentation detailing how base URL’s and relative paths interact:

 NSURL *baseURL = [NSURL URLWithString:@"http://example.com/v1/"]http://example.com/v1/"];
 [NSURL URLWithString:@"foo" relativeToURL:baseURL];                  // http://example.com/v1/foo
 [NSURL URLWithString:@"foo?bar=baz" relativeToURL:baseURL];          // http://example.com/v1/foo?bar=baz
 [NSURL URLWithString:@"/foo" relativeToURL:baseURL];                 // http://example.com/foo
 [NSURL URLWithString:@"foo/" relativeToURL:baseURL];                 // http://example.com/v1/foo
 [NSURL URLWithString:@"/foo/" relativeToURL:baseURL];                // http://example.com/foo/
 [NSURL URLWithString:@"http://example2.com/" relativeToURL:baseURL]; // http://example2.com/

Keep these rules in mind when providing relative paths to the object manager.

Path patterns are a common unit of abstraction in RestKit for describing the path portion of URL’s. When working with API’s, there is typically one or more dynamic portions of the URL that correspond to primary keys or other identifying resource attributes. For example, a blogging application may represent articles in a URL structure such as ‘/articles/1234’ and comments about an article might appear at ‘/articles/1234/comments’. These path structures could be represented as the path patterns ‘/articles/:articleID’ and ‘/articles/:articleID/comments’, substituing the dynamic key ‘:articleID’ in place of the primary key of in the path. These keys can be used to interpolate a path with an object’s property values using key-value coding or be used to match a string.

Path patterns appear throughout RestKit, but the most fundamental uses are for the dynamic generation of URL paths from objects and the matching of request and response URLs for mapping configuration. When generating a URL, a path pattern is interpolated with the value of an object. Consider this example:

// Set object attributes
RKArticle *article = [RKArticle new];
article.articleID = @12345;
// Interpolate with the object
NSString *path = RKPathFromPatternWithObject(@"/articles/:articleID", article);
NSLog(@"The path is %@", path); // prints /articles/12345

This may at first glance appear to provide only a small syntactic improvement over using [NSString stringWithFormat:], but it becomes more interesting once you consider that the dynamic key can include key path:

RKCategory *category = [RKCategory new];
comment.name = @"RestKit;
article.category = category;
NSString *path = RKPathFromPatternWithObject(@"/categories/:comment.name/articles/:articleID/comments/", article);
NSLog(@"The path is %@", path); // prints /categories/RestKit/articles/12345

These path patterns can then be registered with the manager via an RKRoute object (discussed in detail below), enabling one to perform object request operations like so:

RKObjectManager *manager = [RKObjectManager managerWithBaseURL:[NSURL URLWithString:@"http://restkit.org"]http://restkit.org"]];
[manager.router.routeSet addRoute:[RKRoute routeWithClass:[RKArticle class] pathPattern:@"/categories/:comment.name/articles/:articleID/comments/" method:RKRequestMethodGET]];
// Now GET our article object... sending a GET to '/categories/RestKit/articles/12345'
[manager getObject:article path:nil parameters:nil success:^(RKObjectRequestOperation *operation, RKMappingResult *result) {
    NSLog(@"Loading mapping result: %@", result);
} failure:nil];

Once a path pattern has been registered via the routing system, the manager can automatically build full request URL’s when given nothing but the object to be sent.

The second use case of path patterns is in the matching of path into a dictionary of attributes. In this case, the path pattern is evaluatd against a string and used to construct an NSDictionary object containing the matched key paths, optionally including the values of a query string. This functionality is provided via the RKPathMatcher class and is discussed in detail in the accompanying documentation.

Escaping Path Patterns

Note that path patterns will by default interpret anything prefixed with a period that follows a dynamic path segment as a key path. This can cause an issue if you have a dynamic path segment that is followed by a file extension. For example, a path pattern of ‘/categories/:categoryID.json’ would be erroneously interpretted as containing a dynamic path segment whose value is interpolated from the ‘categoryID.json’ key path. This key path evaluation behavior can be suppressed by escaping the period preceding the non-dynamic part of the pattern with two leading slashes, as in ‘/categories/:categoryID\.json’.

Request and Response Descriptors

RestKit centralizes configuration for object mapping configurations into the object manager through RKRequestDescriptor and RKResponseDescriptor objects. A collection of each of these object types are maintained by the manager and used to initialize all RKObjectRequestOperation objects created by the manager.

Request descriptors describe how NSURLRequest objects constructed by the manager will be built by specifying how the attributes and relationships for a given class will be object mapped to construct request parameters and what, if any, root key path the parameters will be nested under. Request descriptor objects can also be used with the RKObjectParameterization class to map an object into an NSDictionary representation that is suitable for use as the parameters of a request.

Response descriptors describe how NSHTTPURLResponse objects loaded by object request operations sent by the manager are to be object mapped into local domain objects. Response descriptors are matched against a given response via URL path matching, parsed content key path matching, or both. The RKMapping object associated from a matched RKResponseDescriptor is given to an instance of RKMapperOperation with the parsed response body to perform object mapping on the response.

To better illustrate these concepts, consider the following example for an imaginary Wiki client application:

@interface RKWikiPage : NSObject
@property (nonatomic, copy) NSString *title;
@property (nonatomic, copy) NSString *body;
@end
// Construct a request mapping for our class
RKObjectMapping *requestMapping = [RKObjectMapping requestMapping];
[requestMapping addAttributeMappingsFromDictionary:@{ @"title": @"title", @"body": @"body" }];
// We wish to generate parameters of the format: 
// @{ @"page": @{ @"title": @"An Example Page", @"body": @"Some example content" } }
RKRequestDescriptor *requestDescriptor = [RKRequestDescriptor requestDescriptorWithMapping:mapping
                                                                               objectClass:[RKWikiPage class]
                                                                               rootKeyPath:@"page"];
// Construct an object mapping for the response
// We are expecting JSON in the format:
// {"page": {"title": "<title value>", "body": "<body value>"}
RKObjectMapping *responseMapping = [RKObjectMapping mappingForClass:[RKWikiPage class]];
[responseMapping addAttributeMappingsFromArray:@[ @"title", @"body" ]];
// Construct a response descriptor that matches any URL (the pathPattern is nil), when the response payload
// contains content nested under the `@"page"` key path, if the response status code is 200 (OK)
RKResponseDescriptor *responseDescriptor = [RKResponseDescriptor responseDescriptorWithMapping:responseMapping
                                                                                   pathPattern:nil
                                                                                       keyPath:@"page"
                                                                                   statusCodes:[NSIndexSet indexSetWithIndex:200]];
// Register our descriptors with a manager
RKObjectManager *manager = [RKObjectManager managerWithBaseURL:[NSURL URLWithString:@"http://restkit.org/"]http://restkit.org/"]];
[manager addRequestDescriptor:requestDescriptor];
[manager addResponseDescriptor:responseDescriptor];
// Work with the object
RKWikiPage *page = [RKWikiPage new];
page.title = @"An Example Page";
page.body  = @"Some example content";
// POST the parameterized representation of the `page` object to `/posts` and map the response
[manager postObject:page path:@"/pages" parameters:nil success:^(RKObjectRequestOperation *operation, RKMappingResult *result) {
    NSLog(@"We object mapped the response with the following result: %@", result);
} failure:nil];

In the above example, request and response mapping configurations were described for a simple data model and then used to perform a basic POST operation and map the results. An arbitrary number of request and response descriptors may be added to the manager to accommodate your application’s needs.

Multi-object Parameterization

The object manager provides support for the parameterization of multiple objects provided as an array. The requestWithObject:method:path:parameters: and multipartFormRequestWithObject:method:path:parameters:constructingBodyWithBlock: methods can parameterize an array of objects for you provided that the RKRequestDescriptor objects are configured in a compatible way. The rules for multi-object parameterization are simple:

1. If a nil root key path is used, then it must be used for all objects in the array. This is because the objects will be parameterized into a dictionary and then each dictionary will be added to an array. This array is then serialized for transport, so objects parameterized to a non-nil key path cannot be merged with the array.
2. If a nil root key path is used to parameterize the array of objects, then you cannot provide additional parameters to be merged with the request. This is again because you cannot merge a dictionary with an array.

If non-nil key paths are used, then each object will be set in the parameters dictionary at the specified key-path. If more than one object uses the same root key path, then the parameters will be combined into an array for transport.

MIME Types

MIME Types serve an important function to the object manager. They are used to identify how content is to be serialized when constructing request bodies and also used to set the ‘Accept’ header for content negotiation. RestKit aspires to be content type agnostic by leveraging the pluggable RKMIMESerialization class to handle content serialization and deserialization.

Routing

Routing is the process of generating an NSURL appropriate for a particular HTTP server request interaction. Using routing instead of hard-coding paths enables centralization of configuration and allows the developer to focus on what they want done rather than the details of how to do it. Changes to the URL structure in the application can be made in one place. Routes can also be useful in testing, as they permit for the changing of paths at run-time.

Routing interfaces are provided by the RKRouter class. Each object manager is in initialized with an RKRouter object with a baseURL equal to the baseURL of the underlying AFHTTPClient object. Each RKRouter instance maintains an RKRouteSet object that manages a collection of RKRoute objects. Routes are defined in terms of a path pattern.

There are three types of routes currently supported:

1. Class Routes. Class routes are configured to target a given object class and HTTP request method. For example, we might route the HTTP GET for a User class to the path pattern @"/users/:userID".
2. Relationship Routes. Relationship routes identify the path appropriate for performing a request for an object that is related to another object. For example, each User may have many friends. This might be routed as a relationship route for the User class with the name @"friends" to the path pattern @"/users/:userID/friends".
3. Named Routes. Names routes bind an arbitrary name to a path. For example, there might be an action to follow another user that could be added as a named route with the name @"follow_user" that generates a POST to the path pattern @"/users/:userID/follow".

To better understand these concepts, please consider the following example code for configuring the above routing examples:

RKObjectManager *manager = [RKObjectManager managerWithBaseURL:[NSURL URLWithString:@"http://restkit.org"]http://restkit.org"]];
// Class Route
[manager.router.routeSet addRoute:[RKRoute routeWithClass:[User class] pathPattern:@"/users/:userID" method:RKRequestMethodGET]];
// Relationship Route
[manager.router.routeSet addRoute:[RKRoute routeWithRelationshipName:@"friends" objectClass:[User class] pathPattern:@"/users/:userID/friends" method:RKRequestMethodGET]];
// Named Route
[manager.router.routeSet addRoute:[RKRoute routeWithName:@"follow_user" pathPattern:@"/users/:userID/follow" method:RKRequestMethodPOST]];

Once configured, routes will be consulted by the object manager whenever the path parameter provided to a method is given as nil. For example, invoking the following code would result in a GET to the path @"/users/1234":

User *user = [User new];
user.userID = 1234;
[manager getObject:user path:nil parameters:nil success:^(RKObjectRequestOperation *operation, RKMappingResult *result) {
    // Request 
} failure:nil];

Routes can also be explicitly used to construct NSMutableURLRequest objects and are referenced explicitly in a few object request operation methods:

1. requestWithObject:method:path:parameters: – Consults routing when path is nil.
2. multipartFormRequestWithObject:method:path:parameters:constructingBodyWithBlock: – Consults routing when path is nil.
3. requestWithPathForRouteNamed:object:parameters: – Explicitly retrieves the route with the given name.
4. getObjectsAtPathForRelationship:ofObject:parameters:success:failure: – Explicitly retrieves the route for the given name and object class.
5. getObjectsAtPathForRouteNamed:object:parameters:success:failure: – Explicitly retrieves the route for the given name.

Please see the documentation for RKRouter, RKRouteSet, and RKRoute for more details about the routing classes.

Metadata Mapping

The RKObjectManager class has integrated support for metadata mapping. Metdata mapping enables the object mapping of supplemental information external to the object representation loaded via an HTTP response. Object request operations constructed by the manager make the following metadata key paths available for mapping:

1. @metadata.routing.parameters – A dictionary whose keys are the key paths matched from the path pattern of the RKRoute object used to construct the request URL and whose values are taken by evaluating the key path against the object interpolated with the route. Only available when routing was used to construct the request URL.
2. @metadata.routing.route – The route object used to construct the request URL.

Please refer to the documentation accompanying RKMappingOperation for more details on metadata mapping.

Core Data

RestKit features deep integration with Apple’s Core Data persistence framework. The object manager provides access to this integration by creating RKManagedObjectRequestOperation objects when an attempt is made to interact with a resource that has been mapped using an RKEntityMapping. To utilize the Core Data integration, the object manager must be provided with a fully configured RKManagedObjectStore object. The RKManagedObjectStore provides access to the NSManagedObjectModel and NSManagedObjectContext objects required to peform object mapping that targets a Core Data entity.

Please see the documentation for RKManagedObjectStore, RKEntityMapping, and RKManagedObjectRequestOperation for in depth information about Core Data in RestKit.

Customization & Subclassing Notes

The object manager is designed to support subclassing. The default behaviors can be altered and tailored to the specific needs of your application easily by manipulating a few core methods:

• requestWithObject:method:path:parameters: – Used to construct all NSMutableURLRequest objects used by the manager.
• objectRequestOperationWithRequest:success:failure: – Used to construct all non-managed object request operations for the manager. Provide a subclass implementation if you wish to alter the behavior of all unmanaged object request operations.
• managedObjectRequestOperationWithRequest:managedObjectContext:success:failure: – Used to construct all managed object request operations for the manager. Provide a subclass implementation if you wish to alter the behavior of all managed object request operations.
• appropriateObjectRequestOperationWithObject:method:path:parameters: – Used to construct all object request operations for the manager, both managed and unmanaged. Invokes either objectRequestOperationWithRequest:success:failure: or managedObjectRequestOperationWithRequest:managedObjectContext:success:failure: to construct the actual request. Provide a subclass implementation to alter behaviors for all object request operations constructed by the manager.
• enqueueObjectRequestOperation: – Invoked to enqueue all operations constructed by the manager that are to be started as soon as possible. Provide a subclass implementation if you wish to work with object request operations as they are be enqueued.

If you wish to more specifically customize the behavior of the lower level HTTP details, you have several options. All HTTP requests made by the RKObjectManager class are made with an instance of the RKHTTPRequestOperation class, which is a subclass of the AFHTTPRequestOperation class from AFNetworking. This operation class implements the NSURLConnectionDelegate and NSURLConnectionDataDelegate protocols and as such, has full access to all details of the HTTP request/response cycle exposed by NSURLConnection. You can provide the object manager with your own custom subclass of RKHTTPRequestOperation to the manager via the setHTTPOperationClass: method and all HTTP requests made through the manager will pass through your operation.

You can also customize the HTTP details at the AFNetworking level by subclassing AFHTTPClient and using an instance of your subclassed client to initialize the manager.