// // RKClient.h // RestKit // // Created by Blake Watters on 7/28/09. // Copyright 2009 Two Toasters. All rights reserved. // #import "RKRequest.h" #import "RKParams.h" #import "RKResponse.h" #import "NSDictionary+RKRequestSerialization.h" #import "RKReachabilityObserver.h" ///////////////////////////////////////////////////////////////////////// /** * URL & URL Path Convenience methods */ /** * Returns an NSURL with the specified resource path appended to the base URL * that the shared RKClient instance is configured with * * Shortcut for calling [[RKClient sharedClient] URLForResourcePath:@"/some/path"] */ NSURL* RKMakeURL(NSString* resourcePath); /** * Returns an NSString with the specified resource path appended to the base URL * that the shared RKClient instance is configured with * * Shortcut for calling [[RKClient sharedClient] URLPathForResourcePath:@"/some/path"] */ NSString* RKMakeURLPath(NSString* resourcePath); /** * Convenience method for generating a path against the properties of an object. Takes * a string with property names encoded in parentheses and interpolates the values of * the properties specified and returns the generated path. * * For example, given an 'article' object with an 'articleID' property of 12345 * RKMakePathWithObject(@"articles/(articleID)", article) would generate @"articles/12345" * * This functionality is the basis for resource path generation in the Router. */ NSString* RKMakePathWithObject(NSString* path, id object); ///////////////////////////////////////////////////////////////////////// /** * RKClient exposes the low level client interface for working * with HTTP servers and RESTful services. It wraps the request/response * cycle with a clean, simple interface. */ @interface RKClient : NSObject { NSString* _baseURL; NSString* _username; NSString* _password; NSMutableDictionary* _HTTPHeaders; RKReachabilityObserver* _baseURLReachabilityObserver; NSString* _serviceUnavailableAlertTitle; NSString* _serviceUnavailableAlertMessage; BOOL _serviceUnavailableAlertEnabled; } /** * The base URL all resources are nested underneath */ @property(nonatomic, retain) NSString* baseURL; /** * The username to use for authentication via HTTP AUTH */ @property(nonatomic, retain) NSString* username; /** * The password to use for authentication via HTTP AUTH */ @property(nonatomic, retain) NSString* password; /** * A dictionary of headers to be sent with each request */ @property(nonatomic, readonly) NSDictionary* HTTPHeaders; /** * The RKReachabilityObserver used to monitor whether or not the client has a connection * path to the baseURL */ @property(nonatomic, readonly) RKReachabilityObserver* baseURLReachabilityObserver; /** * The title to use in the UIAlertView shown when a request encounters a * ServiceUnavailable (503) response. * If not provided, the default is: "Service Unavailable" */ @property(nonatomic, retain) NSString* serviceUnavailableAlertTitle; /** * The message to use in the UIAlertView shown when a request encounters a * ServiceUnavailable (503) response. * If not provided, the default is: "The remote resource is unavailable. Please try again later." */ @property(nonatomic, retain) NSString* serviceUnavailableAlertMessage; /** * Flag that determines whether the Service Unavailable alert is shown in response * to a ServiceUnavailable (503) response. * Defaults to NO. */ @property(nonatomic, assign) BOOL serviceUnavailableAlertEnabled; /** * Return the configured singleton instance of the Rest client */ + (RKClient*)sharedClient; /** * Set the shared singleton issue of the Rest client */ + (void)setSharedClient:(RKClient*)client; /** * Return a Rest client scoped to a particular base URL. If the singleton client is nil, the return client is set as the singleton */ + (RKClient*)clientWithBaseURL:(NSString*)baseURL; /** * Return a Rest client scoped to a particular base URL with a set of HTTP AUTH credentials. If the singleton client is nil, the return client is set as the singleton */ + (RKClient*)clientWithBaseURL:(NSString*)baseURL username:(NSString*)username password:(NSString*)password; /** * Deprecated global instance accessors. Use sharedClient & setSharedClient * @deprecated */ + (RKClient*)client DEPRECATED_ATTRIBUTE; + (void)setClient:(RKClient*)client DEPRECATED_ATTRIBUTE; /** * Will check for network connectivity (to google.com) */ - (BOOL)isNetworkAvailable; /** * Adds an HTTP header to each request dispatched through the Rest client */ - (void)setValue:(NSString*)value forHTTPHeaderField:(NSString*)header; /** * Returns a resource path with a dictionary of query parameters URL encoded and appended */ - (NSString*)resourcePath:(NSString*)resourcePath withQueryParams:(NSDictionary*)queryParams; /** * Returns a NSURL by adding a resource path to the base URL */ - (NSURL*)URLForResourcePath:(NSString*)resourcePath; /** * Returns an NSString by adding a resource path to the base URL */ - (NSString*)URLPathForResourcePath:(NSString*)resourcePath; /** * Returns a NSURL by adding a resource path to the base URL and appending a URL encoded set of query parameters */ - (NSURL*)URLForResourcePath:(NSString *)resourcePath queryParams:(NSDictionary*)queryParams; - (void)setupRequest:(RKRequest*)request; /** * Return a request object targetted at a resource path relative to the base URL. By default the method is set to GET * All headers set on the client will automatically be applied to the request as well. */ - (RKRequest*)requestWithResourcePath:(NSString*)resourcePath delegate:(id)delegate; /////////////////////////////////////////////////////////////////////////////////////////////////////////// // Asynchronous Helper Methods /////////////////////////////////////////////////////////////////////////////////////////////////////////// /** * These methods are provided as a convenience to cover the common asynchronous request tasks. All other request * needs should instantiate a request via requestWithResourcePath:delegate:callback and work with the RKRequest * object directly. */ /** * Fetch a resource via an HTTP GET */ - (RKRequest*)get:(NSString*)resourcePath delegate:(NSObject*)delegate; /** * Fetch a resource via an HTTP GET with a dictionary of params * * Note that this request _only_ allows NSDictionary objects as the params. The dictionary will be coerced into a URL encoded * string and then appended to the resourcePath as the query string of the request. */ - (RKRequest*)get:(NSString*)resourcePath queryParams:(NSDictionary*)queryParams delegate:(NSObject*)delegate; /** * Create a resource via an HTTP POST with a set of form parameters */ - (RKRequest*)post:(NSString*)resourcePath params:(NSObject*)params delegate:(NSObject*)delegate; /** * Update a resource via an HTTP PUT */ - (RKRequest*)put:(NSString*)resourcePath params:(NSObject*)params delegate:(NSObject*)delegate; /** * Destroy a resource via an HTTP DELETE */ - (RKRequest*)delete:(NSString*)resourcePath delegate:(NSObject*)delegate; @end