Inherits from NSObject
Declared in RKObjectManager.h
RKObjectManager.m

Overview

The object manager is the primary interface for interacting with RESTful resources via HTTP. It is responsible for retrieving remote object representations via HTTP and transforming them into local domain objects via the RKObjectMapper. It is also capable of serializing local objects and sending them to a remote system for processing. The object manager strives to hide the developer from the details of configuring an RKRequest, processing an RKResponse, parsing any data returned by the remote system, and running the parsed data through the object mapper.

Shared Manager Instance

Multiple instances of RKObjectManager may be used in parallel, but the first instance initialized is automatically configured as the sharedManager instance. The shared instance can be changed at runtime if so desired. See sharedManager and setSharedManager for details.

Configuring the Object Manager

The object mapper must be configured before object can be loaded from or transmitted to your remote backend system. Configuration consists of specifying the desired MIME types to be used during loads and serialization, registering object mappings to use for mapping and serialization, registering routes, and optionally configuring an instance of the managed object store (for Core Data).

MIME Types

MIME Types are used for two purposes within RestKit:

  1. Content Negotiation. RestKit leverages the HTTP Accept header to specify the desired representation of content when contacting a remote web service. You can specify the MIME Type to use via the acceptMIMEType method. The default MIME Type is RKMIMETypeJSON (application/json). If the remote web service responds with content in a different MIME Type than specified, RestKit will attempt to parse it by consulting the [parser registry][RKParserRegistry parserForMIMEType:]. Failure to find a parser for the returned content will result in an unexpected response invocation of [RKObjectLoaderDelegate objectLoaderDidLoadUnexpectedResponse].
  2. Serialization. RestKit can be used to transport local object representation back to the remote web server for processing by serializing them into an RKRequestSerializable representation. The desired serialization format is configured by setting the serializationMIMEType property. RestKit currently supports serialization to RKMIMETypeFormURLEncoded and RKMIMETypeJSON. The serialization rules themselves are expressed via an instance of RKObjectMapping.

The Mapping Provider

RestKit determines how to map and serialize objects by consulting the mappingProvider. The mapping provider is responsible for providing instances of RKObjectMapper with object mappings that should be used for transforming mappable data into object representations. When you ask the object manager to load or send objects for you, the mappingProvider instance will be used for the object mapping operations constructed for you. In this way, the mappingProvider is the central registry for the knowledge about how objects in your application are mapped.

Mappings are registered by constructing instances of RKObjectMapping and registering them with the provider: `

RKObjectManager* manager = [RKObjectManager managerWithBaseURL:myBaseURL];
RKObjectMapping* articleMapping = [RKObjectMapping mappingForClass:[Article class]];
[mapping mapAttributes:@"title", @"body", @"publishedAt", nil];
[manager.mappingProvider setObjectMapping:articleMapping forKeyPath:@"article"];
// Generate an inverse mapping for transforming Article -> NSMutableDictionary. 
[manager.mappingProvider setSerializationMapping:[articleMapping inverseMapping] forClass:[Article class]];`

Configuring Routes

Routing is the process of transforming objects and actions (as defined by HTTP verbs) into resource paths. RestKit ships

Initializing a Core Data Object Store

Loading Remote Objects

Routing & Object Serialization

Default Error Mapping

When an instance of RKObjectManager is configured, the RKObjectMappingProvider instance configured

Tasks

Configuring the Shared Manager Instance

Initializing an Object Manager

Other Methods

Configuring Object Mapping

  •   mappingProvider

    The Mapping Provider responsible for returning mappings for various keyPaths.

         property
  •   router

    Router object responsible for generating resource paths for HTTP requests

         property
  •   objectStore

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

         property
  •   serializationMIMEType

    The Default MIME Type to be used in object serialization.

         property
  •   acceptMIMEType

    The value for the HTTP Accept header to specify the preferred format for retrieved data

         property
  •   inferMappingsFromObjectTypes

    When YES, RestKit will auto-select the appropriate object mapping for a particular object passed through getObject:, postObject:, putObject:, and deleteObject:.

         property
  • – loadObjectsAtResourcePath:delegate:

    Create and send an asynchronous GET request to load the objects at the resource path and call back the delegate with the loaded objects. Remote objects will be mapped to local objects by consulting the keyPath registrations set on the mapping provider.
  • – loadObjectsAtResourcePath:objectMapping:delegate:

    Load mappable objects at the specified resourcePath using the specified object mapping.

Mappable Object Loaders

  • – getObject:delegate:

    Fetch the data for a mappable object by performing an HTTP GET.
  • – postObject:delegate:

    Create a remote mappable model by POSTing the attributes to the remote resource and loading the resulting objects from the payload
  • – putObject:delegate:

    Update a remote mappable model by PUTing the attributes to the remote resource and loading the resulting objects from the payload
  • – deleteObject:delegate:

    Delete the remote instance of a mappable model by performing an HTTP DELETE on the remote resource
  • – loadObjectsAtResourcePath:delegate:block:

    Load the objects at the specified resource path and perform object mapping on the response payload. Prior to sending the object loader, the block will be invoked to allow you to configure the object loader as you see fit. This can be used to change the response type, set custom parameters, choose an object mapping, etc.
  • – sendObject:delegate:block:

    Configure and send an object loader after yielding it to a block for configuration. This allows for very succinct on-the-fly configuration of the request without obtaining an object reference via objectLoaderForObject: and then sending it yourself.
  • – getObject:delegate:block:

    GET a remote object instance and yield the object loader to the block before sending
  • – postObject:delegate:block:

    POST a remote object instance and yield the object loader to the block before sending
  • – putObject:delegate:block:

    PUT a remote object instance and yield the object loader to the block before sending
  • – deleteObject:delegate:block:

    DELETE a remote object instance and yield the object loader to the block before sending
  • – getObject:mapResponseWith:delegate:

    Fetch the data for a mappable object by performing an HTTP GET. The data returned in the response will be mapped according to the object mapping provided.
  • – postObject:mapResponseWith:delegate:

    Send the data for a mappable object by performing an HTTP POST. The data returned in the response will be mapped according to the object mapping provided.
  • – putObject:mapResponseWith:delegate:

    Send the data for a mappable object by performing an HTTP PUT. The data returned in the response will be mapped according to the object mapping provided.
  • – deleteObject:mapResponseWith:delegate:

    Delete a remote object representation by performing an HTTP DELETE. The data returned in the response will be mapped according to the object mapping provided.
  • – objectLoaderWithResourcePath:delegate:

    Return an object loader ready to be sent. The method defaults to GET and the URL is relative to the baseURL configured on the client. The loader is configured for an implicit objectClass load. This is the best place to begin work if you need to create a slightly different collection loader than what is provided by the loadObjects family of methods.
  • – objectLoaderForObject:method:delegate:

    Returns an object loader configured for transmitting an object instance across the wire. A request will be constructed for you with the resource path configured for you by the Router. This is the best place to begin work if you need a slightly different interaction with the server than what is provided for you by get/post/put/delete object family of methods. Note that this should be used for one-off changes. If you need to substantially modify all your object loads, you are better off subclassing or implementing your own RKRouter for dryness.

Properties

acceptMIMEType

The value for the HTTP Accept header to specify the preferred format for retrieved data

@property (nonatomic, assign) NSString *acceptMIMEType

Declared In

RKObjectManager.h

client

The underlying HTTP client for this manager

@property (nonatomic, retain) RKClient *client

Declared In

RKObjectManager.h

inferMappingsFromObjectTypes

When YES, RestKit will auto-select the appropriate object mapping for a particular object passed through getObject:, postObject:, putObject:, and deleteObject:.

@property (nonatomic, assign) BOOL inferMappingsFromObjectTypes

Discussion

This is useful when you are working with mappable data that is not identifiable via KVC and you are sending/receiving objects of the same type. When YES, RestKit will search the mappingProvider for an object mapping targeting the same type of object that you passed into getObject:, postObject:, :putObject, or deleteObject: and configure the RKObjectLoader to map the payload using that mapping. This is merely a convenience for users who are working entirely with non-KVC mappable data and saves the added step of searching the mapping provider manually.

Default: NO

Declared In

RKObjectManager.h

mappingProvider

The Mapping Provider responsible for returning mappings for various keyPaths.

@property (nonatomic, retain) RKObjectMappingProvider *mappingProvider

Declared In

RKObjectManager.h

objectStore

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

@property (nonatomic, retain) RKManagedObjectStore *objectStore

Declared In

RKObjectManager.h

router

Router object responsible for generating resource paths for HTTP requests

@property (nonatomic, retain) RKObjectRouter *router

Declared In

RKObjectManager.h

serializationMIMEType

The Default MIME Type to be used in object serialization.

@property (nonatomic, retain) NSString *serializationMIMEType

Declared In

RKObjectManager.h

Class Methods

objectManagerWithBaseURL:

Create and initialize a new object manager. If this is the first instance created it will be set as the shared instance

+ (RKObjectManager *)objectManagerWithBaseURL:(NSString *)baseURL

Declared In

RKObjectManager.h

setSharedManager:

Set the shared instance of the object manager

+ (void)setSharedManager:(RKObjectManager *)manager

Declared In

RKObjectManager.h

sharedManager

Return the shared instance of the object manager

+ (RKObjectManager *)sharedManager

Declared In

RKObjectManager.h

Instance Methods

deleteObject:delegate:

Delete the remote instance of a mappable model by performing an HTTP DELETE on the remote resource

- (RKObjectLoader *)deleteObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

deleteObject:delegate:block:

DELETE a remote object instance and yield the object loader to the block before sending

- (RKObjectLoader *)deleteObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate block:(void ( ^ ) ( RKObjectLoader *))block

Declared In

RKObjectManager.h

deleteObject:mapResponseWith:delegate:

Delete a remote object representation by performing an HTTP DELETE. The data returned in the response will be mapped according to the object mapping provided.

- (RKObjectLoader *)deleteObject:(id<NSObject>)object mapResponseWith:(RKObjectMapping *)objectMapping delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

getObject:delegate:

Fetch the data for a mappable object by performing an HTTP GET.

- (RKObjectLoader *)getObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

getObject:delegate:block:

GET a remote object instance and yield the object loader to the block before sending

- (RKObjectLoader *)getObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate block:(void ( ^ ) ( RKObjectLoader *))block

Declared In

RKObjectManager.h

getObject:mapResponseWith:delegate:

Fetch the data for a mappable object by performing an HTTP GET. The data returned in the response will be mapped according to the object mapping provided.

- (RKObjectLoader *)getObject:(id<NSObject>)object mapResponseWith:(RKObjectMapping *)objectMapping delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

initWithBaseURL:

Initialize a new model manager instance

- (id)initWithBaseURL:(NSString *)baseURL

Declared In

RKObjectManager.h

isOnline

True when we are in online mode

- (BOOL)isOnline

Declared In

RKObjectManager.h

loadObjectsAtResourcePath:delegate:

Create and send an asynchronous GET request to load the objects at the resource path and call back the delegate with the loaded objects. Remote objects will be mapped to local objects by consulting the keyPath registrations set on the mapping provider.

- (RKObjectLoader *)loadObjectsAtResourcePath:(NSString *)resourcePath delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

loadObjectsAtResourcePath:delegate:block:

Load the objects at the specified resource path and perform object mapping on the response payload. Prior to sending the object loader, the block will be invoked to allow you to configure the object loader as you see fit. This can be used to change the response type, set custom parameters, choose an object mapping, etc.

- (RKObjectLoader *)loadObjectsAtResourcePath:(NSString *)resourcePath delegate:(id<RKObjectLoaderDelegate>)delegate block:(void ( ^ ) ( RKObjectLoader *))block

Discussion

For example:

- (void)loadObjectWithBlockExample {
    [[RKObjectManager sharedManager] loadObjectsAtResourcePath:@"/monkeys.json" delegate:self block:^(RKObjectLoader* loader) {
        loader.objectMapping = [[RKObjectManager sharedManager].mappingProvider objectMappingForClass:[Monkey class]];
    }
}

Declared In

RKObjectManager.h

loadObjectsAtResourcePath:objectMapping:delegate:

Load mappable objects at the specified resourcePath using the specified object mapping.

- (RKObjectLoader *)loadObjectsAtResourcePath:(NSString *)resourcePath objectMapping:(RKObjectMapping *)objectMapping delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

objectLoaderForObject:method:delegate:

Returns an object loader configured for transmitting an object instance across the wire. A request will be constructed for you with the resource path configured for you by the Router. This is the best place to begin work if you need a slightly different interaction with the server than what is provided for you by get/post/put/delete object family of methods. Note that this should be used for one-off changes. If you need to substantially modify all your object loads, you are better off subclassing or implementing your own RKRouter for dryness.

- (RKObjectLoader *)objectLoaderForObject:(id<NSObject>)object method:(RKRequestMethod)method delegate:(id<RKObjectLoaderDelegate>)delegate

Discussion

// TODO: Cleanup this comment

Declared In

RKObjectManager.h

objectLoaderWithResourcePath:delegate:

Return an object loader ready to be sent. The method defaults to GET and the URL is relative to the baseURL configured on the client. The loader is configured for an implicit objectClass load. This is the best place to begin work if you need to create a slightly different collection loader than what is provided by the loadObjects family of methods.

- (RKObjectLoader *)objectLoaderWithResourcePath:(NSString *)resourcePath delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

postObject:delegate:

Create a remote mappable model by POSTing the attributes to the remote resource and loading the resulting objects from the payload

- (RKObjectLoader *)postObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

postObject:delegate:block:

POST a remote object instance and yield the object loader to the block before sending

- (RKObjectLoader *)postObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate block:(void ( ^ ) ( RKObjectLoader *))block

See Also

  • sendObject:method:delegate:block – (RKObjectLoader)postObject:(id)object delegate:(id<RKObjectLoaderDelegate>)delegate block:(void(^)(RKObjectLoader))block;

Declared In

RKObjectManager.h

postObject:mapResponseWith:delegate:

Send the data for a mappable object by performing an HTTP POST. The data returned in the response will be mapped according to the object mapping provided.

- (RKObjectLoader *)postObject:(id<NSObject>)object mapResponseWith:(RKObjectMapping *)objectMapping delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

putObject:delegate:

Update a remote mappable model by PUTing the attributes to the remote resource and loading the resulting objects from the payload

- (RKObjectLoader *)putObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

putObject:delegate:block:

PUT a remote object instance and yield the object loader to the block before sending

- (RKObjectLoader *)putObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate block:(void ( ^ ) ( RKObjectLoader *))block

Declared In

RKObjectManager.h

putObject:mapResponseWith:delegate:

Send the data for a mappable object by performing an HTTP PUT. The data returned in the response will be mapped according to the object mapping provided.

- (RKObjectLoader *)putObject:(id<NSObject>)object mapResponseWith:(RKObjectMapping *)objectMapping delegate:(id<RKObjectLoaderDelegate>)delegate

Declared In

RKObjectManager.h

sendObject:delegate:block:

Configure and send an object loader after yielding it to a block for configuration. This allows for very succinct on-the-fly configuration of the request without obtaining an object reference via objectLoaderForObject: and then sending it yourself.

- (RKObjectLoader *)sendObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate block:(void ( ^ ) ( RKObjectLoader *))block

Discussion

For example:

- (BOOL)changePassword:(NSString*)newPassword error:(NSError**)error {
    if ([self validatePassword:newPassword error:error]) {
        self.password = newPassword;
        [[RKObjectManager sharedManager] sendObject:self delegate:self block:^(RKObjectLoader* loader) {
            loader.method = RKRequestMethodPOST;
            loader.serializationMIMEType = RKMIMETypeJSON; // We want to send this request as JSON
            loader.targetObject = nil;  // Map the results back onto a new object instead of self
            // Set up a custom serialization mapping to handle this request
            loader.serializationMapping = [RKObjectMapping serializationMappingWithBlock:^(RKObjectMapping* mapping) {
                [mapping mapAttributes:@"password", nil];
            }];
        }];
    }
}

Declared In

RKObjectManager.h