RKClient Class Reference
| Inherits from | NSObject |
| Declared in | RKClient.h RKClient.m |
Overview
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.
RKClient can be thought of as analogous to a web browser or other HTTP user agent. The client’s primary purpose is to configure and dispatch requests to a remote service for processing in a global way. When working with the Network layer, a user will generally construct and dispatch all RKRequest objects via the interfaces exposed by RKClient.
Base URL and Resource Paths
Core to an effective utilization of RKClient is an understanding of the Base URL and Resource Path concepts. The Base URL forms the common beginning part of a complete URL string that is used to access a remote web service. RKClient instances are configured with a Base URL and all requests dispatched through the client will be sent to a URL consisting of the base URL plus the resource path specified. The resource path is simply the remaining part of the URL once all common text is removed.
For example, given a remote web service at http://restkit.org and RESTful services at http://restkit.org/services and http://restkit.org/objects, our base URL would be http://restkit.org and we would have resource paths of /services and /objects.
Base URL’s simplify interaction with remote services by freeing us from having to interpolate strings and construct NSURL objects to get work done. We are also able to quickly retarget an entire application to a different server or API version by changing the base URL. This is commonly done via conditional compilation to create builds against a staging and production server, for example.
Memory Management
Note that memory management of requests sent via RKClient instances are automatically managed for you. When sent, the request is retained by the shared request queue) and is released all request processing has completed. Generally speaking this means that you can dispatch requests and work with the response in the delegate methods without regard for memory management.
Request Serialization
RKClient and RKRequest support the serialization of objects into payloads to be sent as the body of a request. This functionality is commonly used to provide a dictionary of simple values to be encoded and sent as a form encoding with POST and PUT operations. It is worth noting however that this functionality is provided via the RKRequestSerializable protocol and is not specific to NSDictionary objects.
Tasks
Configuring the Client
-
baseURLThe base URL all resources are nested underneath
property -
HTTPHeadersA dictionary of headers to be sent with each request
property -
– isNetworkAvailableWill check for network connectivity to the host specified in the baseURL
-
– setValue:forHTTPHeaderField:Adds an HTTP header to each request dispatched through the client
HTTP Authentication
-
usernameThe username to use for authentication via HTTP AUTH
property -
passwordThe password to use for authentication via HTTP AUTH
property -
baseURLReachabilityObserverThe RKReachabilityObserver used to monitor whether or not the client has a connection path to the baseURL.
property
Service Availability Alerting
-
serviceUnavailableAlertTitleThe title to use in the alert shown when a request encounters a ServiceUnavailable (503) response.
property -
serviceUnavailableAlertMessageThe message to use in the alert shown when a request encounters a ServiceUnavailable (503) response.
property -
serviceUnavailableAlertEnabledFlag that determines whether the Service Unavailable alert is shown in response to a ServiceUnavailable (503) response.
property
Shared Client Instance
-
+ sharedClientReturn the configured singleton instance of the client
-
+ setSharedClient:Set the shared singleton issue of the client, releasing the current singleton (if any)
Initializing a Client
-
+ clientWithBaseURL:Return a client scoped to a particular base URL. If the singleton client is nil, the return client is set as the singleton
-
+ clientWithBaseURL:username:password:Return a Rest client scoped to a particular base URL with a set of HTTP AUTH credentials. If the singleton client) is nil, the client instantiated will become the singleton instance
Constructing Resource Paths and URLs
-
– URLForResourcePath:Returns a NSURL by adding a resource path to the base URL
-
– URLPathForResourcePath:Returns an NSString by adding a resource path to the base URL
-
– resourcePath:withQueryParams:DEPRECATED_ATTRIBUTE:Returns a resource path with a dictionary of query parameters URL encoded and appended
-
– URLForResourcePath:queryParams:Returns a NSURL by adding a resource path to the base URL and appending a URL encoded set of query parameters
Building Requests
-
– setupRequest:Configures a request with the headers and authentication settings applied to this client
-
– requestWithResourcePath:delegate: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.
Sending Asynchronous Requests
-
– get:delegate:Perform an asynchronous GET request for a resource and inform a delegate of the results
-
– get:queryParams:delegate:Fetch a resource via an HTTP GET with a dictionary of params
-
– post:params:delegate:Create a resource via an HTTP POST with a set of form parameters
-
– put:params:delegate:Update a resource via an HTTP PUT
-
– delete:delegate:Destroy a resource via an HTTP DELETE
Properties
HTTPHeaders
A dictionary of headers to be sent with each request
@property (nonatomic, readonly) NSMutableDictionary *HTTPHeadersDeclared In
RKClient.hbaseURL
The base URL all resources are nested underneath
@property (nonatomic, retain) NSString *baseURLDeclared In
RKClient.hbaseURLReachabilityObserver
The RKReachabilityObserver used to monitor whether or not the client has a connection path to the baseURL.
@property (nonatomic, readonly) RKReachabilityObserver *baseURLReachabilityObserverDiscussion
The baseURLReachabilityObserver instance is configured for you automatically when the RKClient instance is configured. By adding observers, one can detect changes in the availability of network access to the remote web service.
See Also
Declared In
RKClient.hpassword
The password to use for authentication via HTTP AUTH
@property (nonatomic, retain) NSString *passwordDeclared In
RKClient.hserviceUnavailableAlertEnabled
Flag that determines whether the Service Unavailable alert is shown in response to a ServiceUnavailable (503) response.
@property (nonatomic, assign) BOOL serviceUnavailableAlertEnabledDiscussion
Default: NO
Declared In
RKClient.hserviceUnavailableAlertMessage
The message to use in the alert shown when a request encounters a ServiceUnavailable (503) response.
@property (nonatomic, retain) NSString *serviceUnavailableAlertMessageDiscussion
Default: “The remote resource is unavailable. Please try again later.”
Declared In
RKClient.hserviceUnavailableAlertTitle
The title to use in the alert shown when a request encounters a ServiceUnavailable (503) response.
@property (nonatomic, retain) NSString *serviceUnavailableAlertTitleDiscussion
Default: “Service Unavailable”
Declared In
RKClient.husername
The username to use for authentication via HTTP AUTH
@property (nonatomic, retain) NSString *usernameDeclared In
RKClient.hClass Methods
clientWithBaseURL:
Return a client scoped to a particular base URL. If the singleton client is nil, the return client is set as the singleton
+ (RKClient *)clientWithBaseURL:(NSString *)baseURLParameters
- baseURL
The baseURL to set for the client. All requests will be relative to this base URL
Return Value
A configured RKClient instance ready to send requests
See Also
Declared In
RKClient.hclientWithBaseURL:username:password:
Return a Rest client scoped to a particular base URL with a set of HTTP AUTH credentials. If the singleton client) is nil, the client instantiated will become the singleton instance
+ (RKClient *)clientWithBaseURL:(NSString *)baseURL username:(NSString *)username password:(NSString *)passwordParameters
- baseURL
The baseURL to set for the client. All requests will be relative to this base URL
- username
The username to use for HTTP Authentication challenges
- password
The password to use for HTTP Authentication challenges
Return Value
A configured RKClient instance ready to send requests
Declared In
RKClient.hsetSharedClient:
Set the shared singleton issue of the client, releasing the current singleton (if any)
+ (void)setSharedClient:(RKClient *)clientParameters
- client
The RKClient instance to set as the new singleton
Declared In
RKClient.hInstance Methods
URLForResourcePath:
Returns a NSURL by adding a resource path to the base URL
- (NSURL *)URLForResourcePath:(NSString *)resourcePathParameters
- resourcePath
The resource path to build a URL against
Return Value
An NSURL constructed by concatenating the baseURL and the resourcePath
Declared In
RKClient.hURLForResourcePath:queryParams:
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 *)queryParamsParameters
- resourcePath
The resource path to append the query parameters onto
- queryParams
A dictionary of query parameters to be URL encoded and appended to the resource path
Return Value
A URL constructed by concatenating the baseURL and the resourcePath with the query parameters appended
Discussion
This is a convenience method for constructing a new resource path that includes a query. For example, when given a resourcePath of /contacts and a dictionary of parameters containing foo=bar and color=red, will return /contacts?foo=bar&color=red
NOTE – Assumes that the resource path does not already contain any query parameters.
Declared In
RKClient.hURLPathForResourcePath:
Returns an NSString by adding a resource path to the base URL
- (NSString *)URLPathForResourcePath:(NSString *)resourcePathParameters
- resourcePath
The resource path to build a URL against
Return Value
A string URL constructed by concatenating the baseURL and the resourcePath
Declared In
RKClient.hdelete:delegate:
Destroy a resource via an HTTP DELETE
- (RKRequest *)delete:(NSString *)resourcePath delegate:(NSObject<RKRequestDelegate> *)delegateParameters
- resourcePath
The resourcePath to target the request at
- delegate
A delegate object to inform of the results
Return Value
The RKRequest object built and sent to the remote system
Declared In
RKClient.hget:delegate:
Perform an asynchronous GET request for a resource and inform a delegate of the results
- (RKRequest *)get:(NSString *)resourcePath delegate:(NSObject<RKRequestDelegate> *)delegateParameters
- resourcePath
The resourcePath to target the request at
- delegate
A delegate object to inform of the results
Return Value
The RKRequest object built and sent to the remote system
Declared In
RKClient.hget:queryParams:delegate:
Fetch a resource via an HTTP GET with a dictionary of params
- (RKRequest *)get:(NSString *)resourcePath queryParams:(NSDictionary *)queryParams delegate:(NSObject<RKRequestDelegate> *)delegateParameters
- resourcePath
The resourcePath to target the request at
- queryParams
A dictionary of query parameters to append to the resourcePath. Assumes that resourcePath does not contain a query string.
- delegate
A delegate object to inform of the results
Return Value
The RKRequest object built and sent to the remote system
Discussion
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.
Declared In
RKClient.hisNetworkAvailable
Will check for network connectivity to the host specified in the baseURL
- (BOOL)isNetworkAvailableReturn Value
YES if the remote host is accessible
See Also
Declared In
RKClient.hpost:params:delegate:
Create a resource via an HTTP POST with a set of form parameters
- (RKRequest *)post:(NSString *)resourcePath params:(NSObject<RKRequestSerializable> *)params delegate:(NSObject<RKRequestDelegate> *)delegateParameters
- resourcePath
The resourcePath to target the request at
- params
A RKRequestSerializable object to use as the body of the request
- delegate
A delegate object to inform of the results
Return Value
The RKRequest object built and sent to the remote system
See Also
Declared In
RKClient.hput:params:delegate:
Update a resource via an HTTP PUT
- (RKRequest *)put:(NSString *)resourcePath params:(NSObject<RKRequestSerializable> *)params delegate:(NSObject<RKRequestDelegate> *)delegateParameters
- resourcePath
The resourcePath to target the request at
- params
A RKRequestSerializable object to use as the body of the request
- delegate
A delegate object to inform of the results
Return Value
The RKRequest object built and sent to the remote system
See Also
Declared In
RKClient.hrequestWithResourcePath:delegate:
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:(NSObject<RKRequestDelegate> *)delegateParameters
- resourcePath
The resource path to configure the request for
- delegate
A delegate to inform of events in the request lifecycle
Return Value
A fully configured RKRequest instance ready for sending
See Also
Declared In
RKClient.hresourcePath:withQueryParams:DEPRECATED_ATTRIBUTE:
Returns a resource path with a dictionary of query parameters URL encoded and appended
- (NSString *)resourcePath:(NSString *)resourcePath withQueryParams:(NSDictionary *)queryParams DEPRECATED_ATTRIBUTEParameters
- resourcePath
The resource path to append the query parameters onto
- queryParams
A dictionary of query parameters to be URL encoded and appended to the resource path
Return Value
A new resource path with the query parameters appended
Discussion
This is a convenience method for constructing a new resource path that includes a query. For example, when given a resourcePath of /contacts and a dictionary of parameters containing foo=bar and color=red, will return /contacts?foo=bar&color=red
NOTE – Assumes that the resource path does not already contain any query parameters.
Declared In
RKClient.hsetValue:forHTTPHeaderField:
Adds an HTTP header to each request dispatched through the client
- (void)setValue:(NSString *)value forHTTPHeaderField:(NSString *)headerParameters
- value
The string value to set for the HTTP header
- header
The HTTP header to add
See Also
Declared In
RKClient.h