Inherits from NSObject
Declared in RKObjectManager.h

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.

The Base URL 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.

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.

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.

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.

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.

Warning: Note that when subclassing AFHTTPClient to change object manager behaviors it is not possible to alter the paramters of requests that are constructed on behalf of the manager. This is because the object manager handles its own serialization and construction of the request body, but defers to the AFHTTPClient for all other details (such as default HTTP headers, etc).

Tasks

Configuring the Shared Manager Instance

Initializing an Object Manager

  • + managerWithBaseURL:

    Creates and returns a new RKObjectManager object initialized with a new AFHTTPClient object that was in turn initialized with the given base URL. The RestKit defaults are applied to the object manager.
  • – initWithHTTPClient:

    Initializes the receiver with the given AFNetworking HTTP client object, adopting the network configuration from the client.

Accessing Object Manager Properties

  •   HTTPClient

    The AFNetworking HTTP client with which the receiver makes requests.

         property
  •   baseURL

    The base URL of the underlying HTTP client.

         property
  •   defaultHeaders

    The default HTTP headers for all NSURLRequest objects constructed by the object manager.

         property
  •   operationQueue

    The operation queue which manages operations enqueued by the object manager.

         property
  •   router

    The router used to generate URL objects for routable requests created by the manager.

         property

Configuring Request and Response MIME Types

Creating Request Objects

Creating Object Request Operations

Managing Enqueued Object Request Operations

Batching Object Request Operations

Making Object Requests by Path

Making Object Requests for an Object

Managing Request and Response Descriptors

Configuring Core Data Integration

Accessing Paginated Resources

  •   paginationMapping

    The object mapping describing how to map pagination metadata from paginated responses.

         property
  • – paginatorWithPathPattern:

    Creates and returns a paginator object configured to paginate the collection resource accessible at the specified path pattern.

Properties

HTTPClient

The AFNetworking HTTP client with which the receiver makes requests.

@property (nonatomic, strong, readonly) AFHTTPClient *HTTPClient

Declared In

RKObjectManager.h

baseURL

The base URL of the underlying HTTP client.

@property (nonatomic, readonly) NSURL *baseURL

Declared In

RKObjectManager.h

defaultHeaders

The default HTTP headers for all NSURLRequest objects constructed by the object manager.

@property (nonatomic, readonly) NSDictionary *defaultHeaders

Discussion

The returned dictionary contains all of the default headers set on the underlying AFHTTPClient object and the value of the ‘Accept’ header set on the object manager, if any.

Declared In

RKObjectManager.h

fetchRequestBlocks

An array of RKFetchRequestBlock blocks used to map NSURL objects into corresponding NSFetchRequest objects.

@property (nonatomic, readonly) NSArray *fetchRequestBlocks

Discussion

When searched, the blocks are iterated in the reverse-order of their registration and the first block with a non-nil return value halts the search.

Declared In

RKObjectManager.h

managedObjectStore

A Core Data backed object store for persisting objects that have been fetched from the Web

@property (nonatomic, strong) RKManagedObjectStore *managedObjectStore

Declared In

RKObjectManager.h

operationQueue

The operation queue which manages operations enqueued by the object manager.

@property (nonatomic, strong) NSOperationQueue *operationQueue

Declared In

RKObjectManager.h

paginationMapping

The object mapping describing how to map pagination metadata from paginated responses.

@property (nonatomic, strong) RKObjectMapping *paginationMapping

Discussion

The object mapping must have an object class of RKPaginator.

Declared In

RKObjectManager.h

requestDescriptors

Returns an array containing the RKRequestDescriptor objects added to the manager.

@property (nonatomic, readonly) NSArray *requestDescriptors

Return Value

An array containing the request descriptors of the receiver. The elements of the array are instances of RKRequestDescriptor.

See Also

Declared In

RKObjectManager.h

requestSerializationMIMEType

The MIME Type to serialize request parameters into when constructing request objects.

@property (nonatomic, strong) NSString *requestSerializationMIMEType

Discussion

The value of the requestSerializationMIMEType is used to obtain an appropriate RKSerialization conforming class from the RKMIMESerialization interface. Parameterized objects and dictionaries of parameters are then serialized for transport using the class registered for the MIME Type. By default, the value is RKMIMETypeFormURLEncoded which means that the request body of all POST, PUT, and PATCH requests will be sent in the URL encoded format. This is analagous to submitting an HTML form via a web browser. Other common formats include RKMIMETypeJSON, which will cause request bodies to be encoded as JSON.

The value given for the requestSerializationMIMEType must correspond to a MIME Type registered via [RKMIMETypeSerialization registerClass:forMIMEType:]. Implementations are provided by default for RKMIMETypeFormURLEncoded and RKMIMETypeJSON.

Default: RKMIMETypeFormURLEncoded or the value of the parameter encoding for the underlying AFHTTPClient.

Declared In

RKObjectManager.h

responseDescriptors

Returns an array containing the RKResponseDescriptor objects added to the manager.

@property (nonatomic, readonly) NSArray *responseDescriptors

Return Value

An array containing the request descriptors of the receiver. The elements of the array are instances of RKRequestDescriptor.

See Also

Declared In

RKObjectManager.h

router

The router used to generate URL objects for routable requests created by the manager.

@property (nonatomic, strong) RKRouter *router

Declared In

RKObjectManager.h

Class Methods

managerWithBaseURL:

Creates and returns a new RKObjectManager object initialized with a new AFHTTPClient object that was in turn initialized with the given base URL. The RestKit defaults are applied to the object manager.

+ (id)managerWithBaseURL:(NSURL *)baseURL

Parameters

baseURL

The base URL with which to initialize the AFHTTPClient object

Return Value

A new RKObjectManager initialized with an AFHTTPClient that was initialized with the given baseURL.

Discussion

When initialized with a base URL, the returned object manager will have a requestSerializationMIMEType with the value of RKMIMETypeFormURLEncoded and a default value for the ‘Accept’ header set to RKMIMETypeJSON.

Declared In

RKObjectManager.h

setSharedManager:

Set the shared instance of the object manager

+ (void)setSharedManager:(RKObjectManager *)manager

Parameters

manager

The new shared manager instance.

Declared In

RKObjectManager.h

sharedManager

Return the shared instance of the object manager

+ (RKObjectManager *)sharedManager

Return Value

The shared manager instance.

Declared In

RKObjectManager.h

Instance Methods

addFetchRequestBlock:

Adds the given RKFetchRequestBlock block to the manager.

- (void)addFetchRequestBlock:(RKFetchRequestBlock)block

Parameters

A

block object to be executed when constructing an NSFetchRequest object from a given NSURL. The block has a return type of NSFetchRequest and accepts a single NSURL argument.

Declared In

RKObjectManager.h

addRequestDescriptor:

Adds a request descriptor to the manager.

- (void)addRequestDescriptor:(RKRequestDescriptor *)requestDescriptor

Parameters

requestDescriptor

The request descriptor object to the be added to the manager.

Declared In

RKObjectManager.h

addRequestDescriptorsFromArray:

Adds the RKRequestDescriptor objects contained in a given array to the manager.

- (void)addRequestDescriptorsFromArray:(NSArray *)requestDescriptors

Parameters

requestDescriptors

An array of RKRequestDescriptor objects to be added to the manager.

Exceptions

NSInvalidArgumentException

Raised if any element of the given array is not an RKRequestDescriptor object.

Declared In

RKObjectManager.h

addResponseDescriptor:

Adds a response descriptor to the manager.

- (void)addResponseDescriptor:(RKResponseDescriptor *)responseDescriptor

Parameters

responseDescriptor

The response descriptor object to the be added to the manager.

Discussion

Adding a response descriptor to the manager sets the baseURL of the descriptor to the baseURL of the manager, causing it to evaluate URL objects relatively.

Declared In

RKObjectManager.h

addResponseDescriptorsFromArray:

Adds the RKResponseDescriptor objects contained in a given array to the manager.

- (void)addResponseDescriptorsFromArray:(NSArray *)responseDescriptors

Parameters

responseDescriptors

An array of RKResponseDescriptor objects to be added to the manager.

Exceptions

NSInvalidArgumentException

Raised if any element of the given array is not an RKResponseDescriptor object.

Declared In

RKObjectManager.h

appropriateObjectRequestOperationWithObject:method:path:parameters:

Creates and returns an object request operation of the appropriate type for the given object, request method, path, and parameters.

- (id)appropriateObjectRequestOperationWithObject:(id)object method:(RKRequestMethod)method path:(NSString *)path parameters:(NSDictionary *)parameters

Parameters

object

The object with which to construct the object request operation. May be nil.

method

The request method for the request.

path

The path to be appended to the HTTP client’s baseURL and set as the URL of the request. If nil, the router is consulted.

parameters

The parameters to be either set as a query string for GET requests, or reverse merged with the parameterization of the object and set as the request HTTP body.

Return Value

A newly created RKObjectRequestOperation or RKManagedObjectRequest operation as deemed appropriate by the manager for the given parameters.

Discussion

The type of object request operation created is determined by evaluating the type of the object given and examining the list of RKResponseDescriptor objects added to the manager.

If the given object is non-nil and inherits from NSManagedObject, then an instance of RKManagedObjectRequestOperation is returned.

If the given object is nil, then the RKResponseDescriptor objects added to the manager are evaluated to determine the type of operation created. In this case, the path of the operation is used to filter the set of RKResponseDescriptor objects to those that may be used to map the response. If the path is nil, the router is consulted to determine an appropriate path with which to perform the matching. If the filtered array of matching response descriptors defines a mapping configuration with an RKEntityMapping object, then an RKManagedObjectRequestOperation is returned; otherwise an RKObjectRequestOperation is returned.

If an RKManagedObjectRequestOperation operation is created, the managed object context used will be the mainQueueManagedObjectContext of the manager’s managedObjectStore.

Warning: The given object must be a single object instance. Collections are not yet supported.

Declared In

RKObjectManager.h

cancelAllObjectRequestOperationsWithMethod:matchingPathPattern:

Cancels all operations in the object manager’s operation queue whose requests match the specified HTTP method and path pattern.

- (void)cancelAllObjectRequestOperationsWithMethod:(RKRequestMethod)method matchingPathPattern:(NSString *)pathPattern

Parameters

method

The HTTP method to match for the cancelled requests, such as RKRequestMethodGET, RKRequestMethodPOST, RKRequestMethodPUT, RKRequestMethodPatch, or RKRequestMethodDELETE. If RKRequestMethodAny, all object request operations with URLs matching the given path pattern will be cancelled.

pathPattern

The pattern to match against the path of the request URL for executing object request operations considered for cancellation.

Discussion

Paths are matches against the path of the NSURL of the NSURLRequest of each RKObjectRequestOperation contained in the receiver’s operation queue using a RKPathMatcher object.

Declared In

RKObjectManager.h

deleteObject:path:parameters:success:failure:

Creates an RKObjectRequestOperation with a DELETE request for the given object, and enqueues it to the manager’s operation queue.

- (void)deleteObject:(id)object path:(NSString *)path parameters:(NSDictionary *)parameters success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

object

The object with which to construct the object request operation. Cannot be nil.

path

The path to be appended to the HTTP client’s base URL and used as the request URL. If nil, the request URL will be obtained by consulting the router for a route registered for the given object’s class and the RKRequestMethodDELETE request method.

parameters

The parameters to be encoded and appended as the query string for the request URL.

success

A block object to be executed when the object request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the RKMappingResult object created by object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

Discussion

The type of object request operation created is determined by invoking appropriateObjectRequestOperationWithObject:method:path:parameters:.

See Also

Declared In

RKObjectManager.h

enqueueBatchOfObjectRequestOperations:progress:completion:

Enqueues a set of RKObjectRequestOperation to the object manager’s operation queue.

- (void)enqueueBatchOfObjectRequestOperations:(NSArray *)operations progress:(void ( ^ ) ( NSUInteger numberOfFinishedOperations , NSUInteger totalNumberOfOperations ))progress completion:(void ( ^ ) ( NSArray *operations ))completion

Parameters

operations

The set of object request operations to be enqueued.

progress

A block object to be executed when an object request operation completes. This block has no return value and takes two arguments: the number of finished operations and the total number of operations initially executed.

completion

A block object to be executed when the object request operations complete. This block has no return value and takes one argument: the list of operations executed.

Declared In

RKObjectManager.h

enqueueBatchOfObjectRequestOperationsWithRoute:objects:progress:completion:

Creates and enqueues an RKObjectRequestOperation to the object manager’s operation queue for each specified object into a batch. Each object request operation is built by evaluating the object against the given route to construct a request path and then invoking appropriateObjectRequestOperationWithObject:method:path:parameters:. When each object request operation finishes, the specified progress block is executed, until all of the request operations have finished, at which point the completion block also executes.

- (void)enqueueBatchOfObjectRequestOperationsWithRoute:(RKRoute *)route objects:(NSArray *)objects progress:(void ( ^ ) ( NSUInteger numberOfFinishedOperations , NSUInteger totalNumberOfOperations ))progress completion:(void ( ^ ) ( NSArray *operations ))completion

Parameters

route

The route specifying the request method and the path pattern with which to construct the request for each object object request operation in the batch.

objects

The set of objects for which to enqueue a batch of object request operations.

progress

A block object to be executed when an object request operation completes. This block has no return value and takes two arguments: the number of finished operations and the total number of operations initially executed.

completion

A block object to be executed when the object request operations complete. This block has no return value and takes one argument: the list of operations executed.

Discussion

Warning: Note that the route type is significant in how that the object request operation is constructed. If the given route is a class route, then the targetObject of the operation will be set to the object for which the operation is being constructed. For named routes and relationship routes, the target object is nil.

Declared In

RKObjectManager.h

enqueueObjectRequestOperation:

Enqueues an RKObjectRequestOperation to the object manager’s operation queue.

- (void)enqueueObjectRequestOperation:(RKObjectRequestOperation *)objectRequestOperation

Parameters

objectRequestOperation

The object request operation to be enqueued.

Declared In

RKObjectManager.h

getObject:path:parameters:success:failure:

Creates an RKObjectRequestOperation with a GET request for the given object, and enqueues it to the manager’s operation queue.

- (void)getObject:(id)object path:(NSString *)path parameters:(NSDictionary *)parameters success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

object

The object with which to construct the object request operation. Cannot be nil.

path

The path to be appended to the HTTP client’s base URL and used as the request URL. If nil, the request URL will be obtained by consulting the router for a route registered for the given object’s class and the RKRequestMethodGET request method.

parameters

The parameters to be encoded and appended as the query string for the request URL.

success

A block object to be executed when the object request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the RKMappingResult object created by object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

Discussion

The type of object request operation created is determined by invoking appropriateObjectRequestOperationWithObject:method:path:parameters:.

See Also

Declared In

RKObjectManager.h

getObjectsAtPath:parameters:success:failure:

Creates an RKObjectRequestOperation with a GET request with a URL for the given path, and enqueues it to the manager’s operation queue.

- (void)getObjectsAtPath:(NSString *)path parameters:(NSDictionary *)parameters success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

path

The path to be appended to the HTTP client’s base URL and used as the request URL.

parameters

The parameters to be encoded and appended as the query string for the request URL.

success

A block object to be executed when the object request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the RKMappingResult object created by object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

Discussion

The type of object request operation created is determined by invoking appropriateObjectRequestOperationWithObject:method:path:parameters:.

See Also

Declared In

RKObjectManager.h

getObjectsAtPathForRelationship:ofObject:parameters:success:failure:

Creates an RKObjectRequestOperation with a GET request for the relationship with the given name of the given object, and enqueues it to the manager’s operation queue.

- (void)getObjectsAtPathForRelationship:(NSString *)relationshipName ofObject:(id)object parameters:(NSDictionary *)parameters success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

relationshipName

The name of the relationship being loaded. Used to retrieve the RKRoute object from the router for the given object’s class and the relationship name. Cannot be nil.

object

The object for which related objects are being loaded. Evaluated against the RKRoute for the relationship for the object’s class with the given name to compute the path. Cannot be nil.

parameters

The parameters to be encoded and appended as the query string for the request URL. May be nil.

success

A block object to be executed when the object request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the mapped result created from object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

@raises NSInvalidArgumentException Raised if no route is configured for a relationship of the given object’s class with the given name.

Discussion

The type of object request operation created is determined by invoking appropriateObjectRequestOperationWithObject:method:path:parameters:.

See Also

Declared In

RKObjectManager.h

getObjectsAtPathForRouteNamed:object:parameters:success:failure:

Creates an RKObjectRequestOperation with a GET request for the URL returned by the router for the given route name, and enqueues it to the manager’s operation queue.

- (void)getObjectsAtPathForRouteNamed:(NSString *)routeName object:(id)object parameters:(NSDictionary *)parameters success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

routeName

The name of the route being loaded. Used to retrieve the RKRoute object from the router with the given name. Cannot be nil.

object

The object to be interpolated against the path pattern of the RKRoute object retrieved with the given name. Used to compute the path to be appended to the HTTP client’s base URL and used as the request URL. May be nil.

parameters

The parameters to be encoded and appended as the query string for the request URL. May be nil.

success

A block object to be executed when the object request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the mapped result created from object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

@raises NSInvalidArgumentException Raised if no route is configured with the given name or the route returned specifies an HTTP method other than GET.

Discussion

The type of object request operation created is determined by invoking appropriateObjectRequestOperationWithObject:method:path:parameters:.

See Also

Declared In

RKObjectManager.h

initWithHTTPClient:

Initializes the receiver with the given AFNetworking HTTP client object, adopting the network configuration from the client.

- (id)initWithHTTPClient:(AFHTTPClient *)client

Parameters

client

The AFNetworking HTTP client with which to initialize the receiver.

Return Value

The receiver, initialized with the given client.

Discussion

This is the designated initializer. If the sharedManager instance is nil, the receiver will be set as the sharedManager. The default headers and parameter encoding of the given HTTP client are adopted by the receiver to initialize the values of the defaultHeaders and requestSerializationMIMEType properties.

Declared In

RKObjectManager.h

managedObjectRequestOperationWithRequest:managedObjectContext:success:failure:

Creates an RKManagedObjectRequestOperation operation with the given request and managed object context, and sets the completion block with the given success and failure blocks.

- (RKManagedObjectRequestOperation *)managedObjectRequestOperationWithRequest:(NSURLRequest *)request managedObjectContext:(NSManagedObjectContext *)managedObjectContext success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

request

The request object to be loaded asynchronously during execution of the operation.

managedObjectContext

The managed object context with which to associate the operation. This context will be used as the parent context of a new operation local NSManagedObjectContext with the NSPrivateQueueConcurrencyType concurrency type. Upon success, the private context will be saved and changes resulting from the object mapping will be ‘pushed’ to the given context.

success

A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the RKMappingResult object created by object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

Return Value

An RKObjectRequestOperation object that is ready to be sent.

Discussion

The given managed object context given will be used as the parent context of the private managed context in which the response is mapped and will be used to fetch the results upon invocation of the success completion block.

Declared In

RKObjectManager.h

multipartFormRequestWithObject:method:path:parameters:constructingBodyWithBlock:

Creates an NSMutableURLRequest object with the specified HTTP method and path, and constructs a multipart/form-data HTTP body, using the specified parameters and multipart form data block. See http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.2

- (NSMutableURLRequest *)multipartFormRequestWithObject:(id)object method:(RKRequestMethod)method path:(NSString *)path parameters:(NSDictionary *)parameters constructingBodyWithBlock:(void ( ^ ) ( id<AFMultipartFormData> formData ))block

Parameters

object

The object with which to construct the request. For the POST, PUT, and PATCH request methods, the object will parameterized using the RKRequestDescriptor for the object.

method

The HTTP method for the request, such as GET, POST, PUT, or DELETE.

path

The path to be appended to the HTTP client’s base URL and used as the request URL. If nil, the router is consulted.

parameters

The parameters to be either set as a query string for GET requests, or reverse merged with the parameterization of the object and set as the request HTTP body.

block

A block that takes a single argument and appends data to the HTTP body. The block argument is an object adopting the AFMultipartFormData protocol. This can be used to upload files, encode HTTP body as JSON or XML, or specify multiple values for the same parameter, as one might for array values.

Return Value

An NSMutableURLRequest object.

Discussion

This method wraps the underlying AFHTTPClient method multipartFormRequestWithMethod:path:parameters:constructingBodyWithBlock and adds routing and object parameterization.

Warning: An exception will be raised if the specified method is not POST, PUT or DELETE.

Declared In

RKObjectManager.h

objectRequestOperationWithRequest:success:failure:

Creates an RKObjectRequestOperation operation with the given request and sets the completion block with the given success and failure blocks.

- (RKObjectRequestOperation *)objectRequestOperationWithRequest:(NSURLRequest *)request success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

request

The request object to be loaded asynchronously during execution of the operation.

success

A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the RKMappingResult object created by object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

Return Value

An RKObjectRequestOperation object that is ready to be sent.

Discussion

Warning: Instances of RKObjectRequestOperation are not capable of mapping the loaded NSHTTPURLResponse into a Core Data entity. Use an instance of RKManagedObjectRequestOperation if the response is to be mapped using an RKEntityMapping.

Declared In

RKObjectManager.h

paginatorWithPathPattern:

Creates and returns a paginator object configured to paginate the collection resource accessible at the specified path pattern.

- (RKPaginator *)paginatorWithPathPattern:(NSString *)pathPattern

Parameters

pathPattern

A patterned URL fragment to be appended to the baseURL of the receiver in order to construct the pattern URL with which to access the paginated collection.

Return Value

The newly created paginator instance.

Discussion

The paginator instantiated will be initialized with a URL built by appending the given pathPattern to the baseURL of the client. The response descriptors and Core Data configuration, if any, are inherited from the receiver.

Warning: Will raise an exception if the value of the paginationMapping property is nil.

See Also

Declared In

RKObjectManager.h

patchObject:path:parameters:success:failure:

Creates an RKObjectRequestOperation with a PATCH request for the given object, and enqueues it to the manager’s operation queue.

- (void)patchObject:(id)object path:(NSString *)path parameters:(NSDictionary *)parameters success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

object

The object with which to construct the object request operation. Cannot be nil.

path

The path to be appended to the HTTP client’s base URL and used as the request URL. If nil, the request URL will be obtained by consulting the router for a route registered for the given object’s class and the RKRequestMethodPATCH method.

parameters

The parameters to be reverse merged with the parameterization of the given object and set as the request body.

success

A block object to be executed when the object request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the RKMappingResult object created by object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

See Also

Declared In

RKObjectManager.h

postObject:path:parameters:success:failure:

Creates an RKObjectRequestOperation with a POST request for the given object, and enqueues it to the manager’s operation queue.

- (void)postObject:(id)object path:(NSString *)path parameters:(NSDictionary *)parameters success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

object

The object with which to construct the object request operation. Cannot be nil.

path

The path to be appended to the HTTP client’s base URL and used as the request URL. If nil, the request URL will be obtained by consulting the router for a route registered for the given object’s class and the RKRequestMethodPOST method.

parameters

The parameters to be reverse merged with the parameterization of the given object and set as the request body.

success

A block object to be executed when the object request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the RKMappingResult object created by object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

See Also

Declared In

RKObjectManager.h

putObject:path:parameters:success:failure:

Creates an RKObjectRequestOperation with a PUT request for the given object, and enqueues it to the manager’s operation queue.

- (void)putObject:(id)object path:(NSString *)path parameters:(NSDictionary *)parameters success:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

object

The object with which to construct the object request operation. Cannot be nil.

path

The path to be appended to the HTTP client’s base URL and used as the request URL. If nil, the request URL will be obtained by consulting the router for a route registered for the given object’s class and the RKRequestMethodPUT method.

parameters

The parameters to be reverse merged with the parameterization of the given object and set as the request body.

success

A block object to be executed when the object request operation finishes successfully. This block has no return value and takes two arguments: the created object request operation and the RKMappingResult object created by object mapping the response data of request.

failure

A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the NSError object describing the network or parsing error that occurred.

See Also

Declared In

RKObjectManager.h

removeRequestDescriptor:

Removes a given request descriptor from the manager.

- (void)removeRequestDescriptor:(RKRequestDescriptor *)requestDescriptor

Parameters

requestDescriptor

An RKRequestDescriptor object to be removed from the manager.

Declared In

RKObjectManager.h

removeResponseDescriptor:

Removes a given response descriptor from the manager.

- (void)removeResponseDescriptor:(RKResponseDescriptor *)responseDescriptor

Parameters

responseDescriptor

An RKResponseDescriptor object to be removed from the manager.

Declared In

RKObjectManager.h

requestWithObject:method:path:parameters:

Creates and returns an NSMutableURLRequest object with a given object, method, path, and parameters.

- (NSMutableURLRequest *)requestWithObject:(id)object method:(RKRequestMethod)method path:(NSString *)path parameters:(NSDictionary *)parameters

Parameters

object

The object with which to construct the request. For the POST, PUT, and PATCH request methods, the object will parameterized using the RKRequestDescriptor for the object.

method

The HTTP method for the request, such as GET, POST, PUT, or DELETE.

path

The path to be appended to the HTTP client’s base URL and used as the request URL. If nil, the router is consulted.

parameters

The parameters to be either set as a query string for GET requests, or reverse merged with the parameterization of the object and set as the request HTTP body.

Return Value

An NSMutableURLRequest object.

Discussion

The manager is searched for an RKRequestDescriptor object with an objectClass that matches the class of the given object. If found, the matching request descriptor and object are used to build a parameterization of the object’s attributes using the RKObjectParameterization class if the request method is a POST, PUT, or PATCH. The parameterized representation of the object is reverse merged with the given parameters dictionary, if any, and then serialized and set as the request body. If the HTTP method is GET or DELETE, the object will not be parameterized and the given parameters, if any, will be used to construct a url-encoded query string that is appended to the request’s URL.

If the given path is nil, the router is searched for a class route with the class of the object andthe method. The path pattern of the retrieved route is interpolated with the object and the resulting path is appended to the HTTP client’s base URL and used as the request URL.

See Also

Declared In

RKObjectManager.h

requestWithPathForRelationship:ofObject:method:parameters:

Creates an NSMutableURLRequest object with the NSURL returned by the router for the relationship of the given object and the given parameters.

- (NSMutableURLRequest *)requestWithPathForRelationship:(NSString *)relationship ofObject:(id)object method:(RKRequestMethod)method parameters:(NSDictionary *)parameters

Parameters

object

The object for which related objects are being loaded. Evaluated against the RKRoute for the relationship for the object’s class with the given name to compute the path. Cannot be nil.

method

The HTTP method for the request.

parameters

The parameters to be encoded and appended as the query string for the request URL, or parameterized and set as the request body. May be nil.

relationshipName

The name of the relationship being loaded. Used to retrieve the RKRoute object from the router for the given object’s class and the relationship name. Cannot be nil.

Return Value

An NSMutableURLRequest object for the specified relationship.

@raises NSInvalidArgumentException Raised if no route is configured for a relationship of the given object’s class with the given name.

Discussion

The implementation invokes requestWithObject:method:path:parameters: after constructing the path with the given route.

Creates an RKObjectRequestOperation with a GET request for the relationship with the given name of the given object, and enqueues it to the manager’s operation queue.

Declared In

RKObjectManager.h

requestWithPathForRouteNamed:object:parameters:

Creates an NSMutableURLRequest object with the NSURL returned by the router for the given route name and object and the given parameters.

- (NSMutableURLRequest *)requestWithPathForRouteNamed:(NSString *)routeName object:(id)object parameters:(NSDictionary *)parameters

Parameters

routeName

The name of the route object containing the path pattern which is to be interpolated against the given object, appended to the HTTP client’s base URL and used as the request URL.

object

The object with which to interpolate the path pattern of the named route. Can be nil.

parameters

The parameters to be either set as a query string for GET requests, or the request HTTP body.

Return Value

An NSMutableRequest object.

Discussion

The implementation invokes requestWithObject:method:path:parameters: after constructing the path with the given route.

Declared In

RKObjectManager.h

setAcceptHeaderWithMIMEType:

The value for the HTTP “Accept” header to specify the preferred serialization format for retrieved data.

- (void)setAcceptHeaderWithMIMEType:(NSString *)MIMEType

Parameters

MIMEType

The MIME Type to set as the value for the HTTP “Accept” header.

Discussion

If the receiver was initialized with an AFHTTPClient, then the value of the ‘Accept’ header is deferred to the client. If initialized directly with a baseURL, the default value is RKMIMETypeJSON, which is equal to the string @"application/json". A value of nil will prevent the object manager from explicitly setting a value for the “Accept” header.

Declared In

RKObjectManager.h

setHTTPOperationClass:

Sets the RKHTTPRequestOperation subclass to be used when constructing HTTP request operations for requests dispatched through the manager.

- (void)setHTTPOperationClass:(Class)operationClass

Parameters

operationClass

A class object inheriting from RKHTTPRequestOperation to be used for HTTP requests dispatched through the manager. @raises NSInvalidArgumentException Raised if the given class does not inherit from RKHTTPRequestOperation.

Discussion

When set, an instance of the given class will be initialized via initWithRequest: each time that the receiver constructs an HTTP request operation. HTTP request operations are used to initialize instances of RKObjectRequestOperation and are responsible for managing the HTTP request/response lifecycle of a request whose response is destined to be object mapped. Providing a subclass implementation of RKHTTPRequestOperation allows the behavior of all requests sent through the manager to be changed.

Warning: The given class must inherit from RKHTTPRequestOperation, else an exception will be raised.

Declared In

RKObjectManager.h