Inherits from NSObject
Declared in RKRequest.h
RKRequest.m

Overview

Models the request portion of an HTTP request/response cycle.

Tasks

Creating a Request

Setting Properties

  •   URL

    The URL this request is loading

         property
  •   resourcePath

    The resourcePath portion of the request’s URL

         property
  •   method

    The HTTP verb in which the request is sent

         property
  •   HTTPMethod

    Returns HTTP method as a string used for this request.

         property
  •   response

    The response returned when the receiver was sent.

         property
  •   params

    A serializable collection of parameters sent as the HTTP body of the request

         property
  •   additionalHTTPHeaders

    A dictionary of additional HTTP Headers to send with the request

         property
  •   runLoopMode

    The run loop mode under which the underlying NSURLConnection is performed

         property
  •   userData

    An opaque pointer to associate user defined data with the request.

         property
  •   URLRequest

    The underlying NSMutableURLRequest sent for this request

         property
  •   defaultHTTPEncoding

    The default value used to decode HTTP body content when HTTP headers received do not provide information on the content. This encoding will be used by the RKResponse when creating the body content

         property

Working with the HTTP Body

  • – setBody:forMIMEType:

    Sets the request body using the provided NSDictionary after passing the NSDictionary through serialization using the currently configured parser for the provided MIMEType.
  •   HTTPBody

    The HTTP body as a NSData used for this request

         property
  •   HTTPBodyString

    The HTTP body as a string used for this request

         property

Delegates

  •   delegate

    The delegate to inform when the request is completed

         property
  •   configurationDelegate

    A delegate responsible for configuring the request. Centralizes common configuration data (such as HTTP headers, authentication information, etc) for re-use.

         property

Handling Blocks

Background Tasks

Authentication

  •   authenticationType

    The type of authentication to use for this request.

         property
  •   username

    The username to use for authentication via HTTP AUTH.

         property
  •   password

    The password to use for authentication via HTTP AUTH.

         property

OAuth1 Secrets

OAuth2 Secrets

Caching

Handling SSL Validation

Sending and Managing the Request

Resetting the State

Callbacks

Timing Out the Request

Determining the Request Type and State

Properties

HTTPBody

The HTTP body as a NSData used for this request

@property (nonatomic, retain) NSData *HTTPBody

Declared In

RKRequest.h

HTTPBodyString

The HTTP body as a string used for this request

@property (nonatomic, retain) NSString *HTTPBodyString

Declared In

RKRequest.h

HTTPMethod

Returns HTTP method as a string used for this request.

@property (nonatomic, readonly) NSString *HTTPMethod

Discussion

This should be set through the method property using an RKRequestMethod type.

See Also

Declared In

RKRequest.h

OAuth1AccessToken

The OAuth 1.0 access token

@property (nonatomic, retain) NSString *OAuth1AccessToken

Discussion

Used to build an Authorization header when authenticationType is RKRequestAuthenticationTypeOAuth1

See Also

Declared In

RKRequest.h

OAuth1AccessTokenSecret

The OAuth 1.0 access token secret

@property (nonatomic, retain) NSString *OAuth1AccessTokenSecret

Discussion

Used to build an Authorization header when authenticationType is RKRequestAuthenticationTypeOAuth1

See Also

Declared In

RKRequest.h

OAuth1ConsumerKey

The OAuth 1.0 consumer key

@property (nonatomic, retain) NSString *OAuth1ConsumerKey

Discussion

Used to build an Authorization header when authenticationType is RKRequestAuthenticationTypeOAuth1

See Also

Declared In

RKRequest.h

OAuth1ConsumerSecret

The OAuth 1.0 consumer secret

@property (nonatomic, retain) NSString *OAuth1ConsumerSecret

Discussion

Used to build an Authorization header when authenticationType is RKRequestAuthenticationTypeOAuth1

See Also

Declared In

RKRequest.h

OAuth2AccessToken

The OAuth 2.0 access token

@property (nonatomic, retain) NSString *OAuth2AccessToken

Discussion

Used to build an Authorization header when authenticationType is RKRequestAuthenticationTypeOAuth2

See Also

Declared In

RKRequest.h

OAuth2RefreshToken

The OAuth 2.0 refresh token

@property (nonatomic, retain) NSString *OAuth2RefreshToken

Discussion

Used to retrieve a new access token before expiration and to build an Authorization header when authenticationType is RKRequestAuthenticationTypeOAuth2

Bug: NOT IMPLEMENTED: This functionality is not yet implemented.

See Also

Declared In

RKRequest.h

URL

The URL this request is loading

@property (nonatomic, retain) NSURL *URL

Declared In

RKRequest.h

URLRequest

The underlying NSMutableURLRequest sent for this request

@property (nonatomic, readonly) NSMutableURLRequest *URLRequest

Declared In

RKRequest.h

additionalHTTPHeaders

A dictionary of additional HTTP Headers to send with the request

@property (nonatomic, retain) NSDictionary *additionalHTTPHeaders

Declared In

RKRequest.h

additionalRootCertificates

A set of additional certificates to be used in evaluating server SSL certificates.

@property (nonatomic, retain) NSSet *additionalRootCertificates

Declared In

RKRequest.h

authenticationType

The type of authentication to use for this request.

@property (nonatomic, assign) RKRequestAuthenticationType authenticationType

Discussion

This must be assigned one of the following:

  • RKRequestAuthenticationTypeNone: Disable the use of authentication
  • RKRequestAuthenticationTypeHTTP: Use NSURLConnection’s HTTP AUTH auto-negotiation
  • RKRequestAuthenticationTypeHTTPBasic: Force the use of HTTP Basic authentication. This will supress AUTH challenges as RestKit will add an Authorization header establishing login via HTTP basic. This is an optimization that skips the challenge portion of the request.
  • RKRequestAuthenticationTypeOAuth1: Enable the use of OAuth 1.0 authentication. OAuth1ConsumerKey, OAuth1ConsumerSecret, OAuth1AccessToken, and OAuth1AccessTokenSecret must be set.
  • RKRequestAuthenticationTypeOAuth2: Enable the use of OAuth 2.0 authentication. OAuth2AccessToken must be set.

Default: RKRequestAuthenticationTypeNone

Declared In

RKRequest.h

backgroundPolicy

The policy to take on transition to the background (iOS 4.x and higher only)

@property (nonatomic, assign) RKRequestBackgroundPolicy backgroundPolicy

Discussion

Default: RKRequestBackgroundPolicyCancel

Declared In

RKRequest.h

backgroundTaskIdentifier

Returns the identifier of the task that has been sent to the background.

@property (nonatomic, readonly) UIBackgroundTaskIdentifier backgroundTaskIdentifier

Declared In

RKRequest.h

cache

The request cache to store and load responses for this request.

@property (nonatomic, retain) RKRequestCache *cache

Discussion

Generally configured by the RKClient instance that minted this request

This must be assigned one of the following:

  • RKRequestCachePolicyNone: Never use the cache.
  • RKRequestCachePolicyLoadIfOffline: Load from the cache when offline.
  • RKRequestCachePolicyLoadOnError: Load from the cache if an error is encountered.
  • RKRequestCachePolicyEtag: Load from the cache if there is data stored and the server returns a 304 (Not Modified) response.
  • RKRequestCachePolicyEnabled: Load from the cache whenever data has been stored.
  • RKRequestCachePolicyTimeout: Load from the cache if the cacheTimeoutInterval is reached before the server responds.

Declared In

RKRequest.h

cacheKey

Returns the cache key for getting/setting the cache entry for this request in the cache.

@property (nonatomic, readonly) NSString *cacheKey

Discussion

The cacheKey is an MD5 value computed by hashing a combination of the destination URL, the HTTP verb, and the request body (when possible).

Declared In

RKRequest.h

cachePolicy

The cache policy used when storing this request into the request cache

@property (nonatomic, assign) RKRequestCachePolicy cachePolicy

Declared In

RKRequest.h

cacheTimeoutInterval

The timeout interval within which the request should not be sent and the cached response should be used. Used if the cache policy includes RKRequestCachePolicyTimeout.

@property (nonatomic, assign) NSTimeInterval cacheTimeoutInterval

Declared In

RKRequest.h

cancelled

Returns a Boolean value indicating whether the request has been cancelled.

@property (nonatomic, assign, readonly, getter=isCancelled) BOOL cancelled

Return Value

YES if the request was sent a cancel message, otherwise NO.

Declared In

RKRequest.h

configurationDelegate

A delegate responsible for configuring the request. Centralizes common configuration data (such as HTTP headers, authentication information, etc) for re-use.

@property (nonatomic, assign) id<> configurationDelegate

Discussion

RKClient and RKObjectManager conform to the RKConfigurationDelegate protocol. Request and object loader instances built through these objects will have a reference to their parent client/object manager assigned as the configuration delegate.

Default: nil

See Also

Declared In

RKRequest.h

defaultHTTPEncoding

The default value used to decode HTTP body content when HTTP headers received do not provide information on the content. This encoding will be used by the RKResponse when creating the body content

@property (nonatomic, assign) NSStringEncoding defaultHTTPEncoding

Declared In

RKRequest.h

delegate

The delegate to inform when the request is completed

@property (nonatomic, assign) id<> delegate

Discussion

If the object implements the RKRequestDelegate protocol, it will receive request lifecycle event messages.

Declared In

RKRequest.h

disableCertificateValidation

Flag for disabling SSL certificate validation.

@property (nonatomic, assign) BOOL disableCertificateValidation

Discussion

When YES, SSL certificates will not be validated.

Default: NO

Warning: WARNING: This is a potential security exposure and should be used ONLY while debugging in a controlled environment.

Declared In

RKRequest.h

followRedirect

Whether this request should follow server redirects or not.

@property (nonatomic, assign) BOOL followRedirect

Discussion

@default YES

Declared In

RKRequest.h

loaded

Returns YES when this request has been completed

@property (nonatomic, assign, readonly, getter=isLoaded) BOOL loaded

Declared In

RKRequest.h

loading

Returns YES when this request is in-progress

@property (nonatomic, assign, readonly, getter=isLoading) BOOL loading

Declared In

RKRequest.h

method

The HTTP verb in which the request is sent

@property (nonatomic, assign) RKRequestMethod method

Discussion

Default: RKRequestMethodGET

Declared In

RKRequest.h

onDidFailLoadWithError

A block to invoke when the receuver has failed loading due to an error.

@property (nonatomic, copy) RKRequestDidFailLoadWithErrorBlock onDidFailLoadWithError

See Also

Declared In

RKRequest.h

onDidLoadResponse

A block to invoke when the receiver has loaded a response.

@property (nonatomic, copy) RKRequestDidLoadResponseBlock onDidLoadResponse

See Also

Declared In

RKRequest.h

params

A serializable collection of parameters sent as the HTTP body of the request

@property (nonatomic, retain) NSObject<RKRequestSerializable> *params

Declared In

RKRequest.h

password

The password to use for authentication via HTTP AUTH.

@property (nonatomic, retain) NSString *password

Discussion

Used to respond to an authentication challenge when authenticationType is RKRequestAuthenticationTypeHTTP or RKRequestAuthenticationTypeHTTPBasic.

See Also

Declared In

RKRequest.h

queue

The request queue that this request belongs to

@property (nonatomic, assign) RKRequestQueue *queue

Declared In

RKRequest.h

reachabilityObserver

The reachability observer to consult for network status. Used for performing offline cache loads.

@property (nonatomic, retain) RKReachabilityObserver *reachabilityObserver

Discussion

Generally configured by the RKClient instance that minted this request.

Declared In

RKRequest.h

resourcePath

The resourcePath portion of the request’s URL

@property (nonatomic, retain) NSString *resourcePath

Declared In

RKRequest.h

response

The response returned when the receiver was sent.

@property (nonatomic, retain, readonly) RKResponse *response

Declared In

RKRequest.h

runLoopMode

The run loop mode under which the underlying NSURLConnection is performed

@property (nonatomic, copy) NSString *runLoopMode

Discussion

Default: NSRunLoopCommonModes

Declared In

RKRequest.h

timeoutInterval

The timeout interval within which the request should be cancelled if no data has been received.

@property (nonatomic, assign) NSTimeInterval timeoutInterval

Discussion

The timeout timer is cancelled as soon as we start receiving data and are expecting the request to finish.

Default: 120.0 seconds

Declared In

RKRequest.h

userData

An opaque pointer to associate user defined data with the request.

@property (nonatomic, retain) id userData

Declared In

RKRequest.h

username

The username to use for authentication via HTTP AUTH.

@property (nonatomic, retain) NSString *username

Discussion

Used to respond to an authentication challenge when authenticationType is RKRequestAuthenticationTypeHTTP or RKRequestAuthenticationTypeHTTPBasic.

See Also

Declared In

RKRequest.h

Class Methods

requestWithURL:

Creates and returns a RKRequest object initialized to load content from a provided URL.

+ (RKRequest *)requestWithURL:(NSURL *)URL

Parameters

URL

The remote URL to load

Return Value

An autoreleased RKRequest object initialized with URL.

Declared In

RKRequest.h

requestWithURL:delegate:

Creates and returns a RKRequest object initialized to load content from a provided URL with a specified delegate.

+ (RKRequest *)requestWithURL:(NSURL *)URL delegate:(id)delegate

Parameters

URL

The remote URL to load

delegate

The delegate that will handle the response callbacks.

Return Value

An autoreleased RKRequest object initialized with URL.

Discussion

Bug: DEPRECATED in v0.10.0: Use [RKRequest requestWithURL:] instead

Declared In

RKRequest.h

Instance Methods

cancel

Cancels the underlying URL connection.

- (void)cancel

Discussion

This will call the requestDidCancel: delegate method if your delegate responds to it. This does not subsequently set the the request’s delegate to nil. However, it’s good practice to cancel the RKRequest and immediately set the delegate property to nil within the delegate’s dealloc method.

See Also

Declared In

RKRequest.h

createTimeoutTimer

Creates a timeoutTimer to trigger the timeout method

- (void)createTimeoutTimer

Discussion

This is mainly used so we can test that the timer is only being created once.

Declared In

RKRequest.h

didFailLoadWithError:

Callback performed to notify the request that the underlying NSURLConnection has failed with an error.

- (void)didFailLoadWithError:(NSError *)error

Parameters

error

An NSError object containing the RKRestKitError that triggered the callback.

Declared In

RKRequest.h

didFinishLoad:

Callback performed to notify the request that the underlying NSURLConnection has completed with a response.

- (void)didFinishLoad:(RKResponse *)response

Parameters

response

An RKResponse object with the result of the request.

Declared In

RKRequest.h

initWithURL:

Initializes a RKRequest object to load from a provided URL

- (id)initWithURL:(NSURL *)URL

Parameters

URL

The remote URL to load

Return Value

An RKRequest object initialized with URL.

Declared In

RKRequest.h

initWithURL:delegate:

Initializes a RKRequest object to load from a provided URL

- (id)initWithURL:(NSURL *)URL delegate:(id)delegate

Parameters

URL

The remote URL to load

delegate

The delegate that will handle the response callbacks.

Return Value

An RKRequest object initialized with URL.

Discussion

Bug: DEPRECATED in v0.10.0: Use [RKRequest initWithURL:] instead

Declared In

RKRequest.h

invalidateTimeoutTimer

Invalidates the timeout timer.

- (void)invalidateTimeoutTimer

Discussion

Called by RKResponse when the NSURLConnection begins receiving data.

Declared In

RKRequest.h

isCacheable

Returns YES if the request is cacheable

- (BOOL)isCacheable

Discussion

Only GET requests are considered cacheable (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)..)

Declared In

RKRequest.h

isDELETE

Returns YES when this is a DELETE request

- (BOOL)isDELETE

Declared In

RKRequest.h

isGET

Returns YES when this is a GET request

- (BOOL)isGET

Declared In

RKRequest.h

isHEAD

Returns YES when this is a HEAD request

- (BOOL)isHEAD

Declared In

RKRequest.h

isPOST

Returns YES when this is a POST request

- (BOOL)isPOST

Declared In

RKRequest.h

isPUT

Returns YES when this is a PUT request

- (BOOL)isPUT

Declared In

RKRequest.h

isUnsent

Returns YES when this request has not yet been sent

- (BOOL)isUnsent

Declared In

RKRequest.h

prepareURLRequest

- (BOOL)prepareURLRequest

Declared In

RKRequest.h

reset

- (void)reset

Declared In

RKRequest.h

send

Send the request asynchronously. It will be added to the queue and dispatched as soon as possible.

- (void)send

Declared In

RKRequest.h

sendAsynchronously

Immediately dispatch a request asynchronously, skipping the request queue.

- (void)sendAsynchronously

Declared In

RKRequest.h

sendSynchronously

Send the request synchronously and return a hydrated response object.

- (RKResponse *)sendSynchronously

Return Value

An RKResponse object with the result of the request.

Declared In

RKRequest.h

setBody:forMIMEType:

Sets the request body using the provided NSDictionary after passing the NSDictionary through serialization using the currently configured parser for the provided MIMEType.

- (void)setBody:(NSDictionary *)body forMIMEType:(NSString *)MIMEType

Parameters

body

An NSDictionary of key/value pairs to be serialized and sent as the HTTP body.

MIMEType

The MIMEType for the parser to use for the dictionary.

Declared In

RKRequest.h

timeout

Cancels request due to connection timeout exceeded.

- (void)timeout

Discussion

This method is invoked by the timeoutTimer upon its expiration and will return an RKRequestConnectionTimeoutError via didFailLoadWithError:

Declared In

RKRequest.h

wasSentToResourcePath:

Returns YES when the request was sent to the specified resource path

- (BOOL)wasSentToResourcePath:(NSString *)resourcePath

Parameters

resourcePath

A string of the resource path that we want to check against

Declared In

RKRequest.h

wasSentToResourcePath:method:

Returns YES when the receiver was sent to the specified resource path with a given request method.

- (BOOL)wasSentToResourcePath:(NSString *)resourcePath method:(RKRequestMethod)method

Parameters

resourcePath

A string of the resource path that we want to check against

method

The HTTP method to confirm the request was sent with.

Declared In

RKRequest.h