HRRestModel Class Reference

#import <HRRestModel.h>

List of all members.


Static Public Member Functions

Setting default request options
Set the default options that can be used in every request made from the model that sets them.

(NSObject *) + delegate
(void) + setDelegate:
(NSURL *) + baseURL
(void) + setBaseURL:
(NSDictionary *) + headers
(void) + setHeaders:
(NSDictionary *) + basicAuth
(void) + setBasicAuthWithUsername:password:
(NSDictionary *) + defaultParams
(void) + setDefaultParams:
(HRDataFormat) + format
(void) + setFormat:
Sending Requests
These methods allow you to send GET, POST, PUT and DELETE requetsts.

Request Options

All requests can take numerous types of options passed as the second argument.

  • headers NSDictionary - The headers to send with the request
  • params NSDictionary - The query or body parameters sent with the request.
  • body NSData, NSString or NSDictionary - This option is used only during POST and PUT requests. This option is eventually transformed into an NSData object before it is sent. If you supply the body as an NSDictionary it's turned to a query string &foo=bar&baz=boo and then it's encoded as an NSData object. If you supply an NSString, it's encoded as an NSData object and sent.


(NSOperation *) + getPath:withOptions:object:
(NSOperation *) + postPath:withOptions:object:
(NSOperation *) + putPath:withOptions:object:
(NSOperation *) + deletePath:withOptions:object:

Detailed Description

This class allows you to easily interact with RESTful resources. Responses are automatically converted to the proper Objective-C type. You can use this class directly or subclass it.

Using this class directly means that all requests share the same configuration (including delegate). This works fine for simple situations but when you start dealing with different resource types it's best to subclass HRRestModel, giving each class its own set of configuation options.

In the code below all requests originating from Person will have an api_key default parameter, the same base url, and the same delegate. See HRResponseDelegate for the the delegate methods available to you.

  @implementation Person
  + (void)initialize {
     [self setDelegate:self];
     NSDictionary *params = [NSDictionary dictionaryWithObject:@"1234567" forKey:@"api_key"];
     [self setBaseURL:[NSURL URLWithString:@"http://localhost:1234/api"]];    
     [self setDefaultParameters:params];
  }

 + (void)restConnection:(NSURLConnection *)connection didReturnResource:(id)resource object:(id)object {
      for(id person in resource) {
          // do something with a person dictionary   
      }  
  }
  @end

  // Would send a request to http://localhost:1234/api/people/1?api_key=1234567
  [Person getPath:@"/people/1" withOptions:nil object:nil];

A note on default properties and subclassing

Each subclass has its own set of unique properties and these properties are not inherited by any additional subclasses.

Member Function Documentation

+ (NSURL *) baseURL  

The base url to use in every request

+ (NSDictionary *) basicAuth  

Returns a dictionary containing the username and password used for basic auth.

+ (NSDictionary *) defaultParams  

Default params sent with every request.

+ (NSObject *) delegate  

Returns the HRResponseDelegate

+ (NSOperation *) deletePath: (NSString *)  path
withOptions: (NSDictionary *)  options
object: (id)  object 

Send a DELETE request

Parameters:
path The path to DELETE. If you haven't setup the baseURL option you'll need to provide a full url.
options The options for this request.
object An object to be passed to the delegate methods

+ (HRDataFormat) format  

The format used to decode and encode request and responses. Supported formats are JSON and XML.

+ (NSOperation *) getPath: (NSString *)  path
withOptions: (NSDictionary *)  options
object: (id)  object 

Send a GET request

Parameters:
path The path to get. If you haven't setup the baseURL option you'll need to provide a full url.
options The options for this request.
object An object to be passed to the delegate methods

+ (NSDictionary *) headers  

Default headers sent with every request

+ (NSOperation *) postPath: (NSString *)  path
withOptions: (NSDictionary *)  options
object: (id)  object 

Send a POST request

Parameters:
path The path to POST to. If you haven't setup the baseURL option you'll need to provide a full url.
options The options for this request.
object An object to be passed to the delegate methods
Note: If you'd like to post raw data like JSON or XML you'll need to set the body option.

+ (NSOperation *) putPath: (NSString *)  path
withOptions: (NSDictionary *)  options
object: (id)  object 

Send a PUT request

Parameters:
path The path to PUT to. If you haven't setup the baseURL option you'll need to provide a full url.
options The options for this request.
object An object to be passed to the delegate methods
Remarks:
Note: All data found in the body option will be PUT. Setting the body option will cause the params option to be ignored.

+ (void) setBaseURL: (NSURL *)  url  

Set the base URL to be used in every request.

Instead of providing a URL for every request you can set the base url here. You can also provide a path and port if you wish. This url is prepended to the path argument of the request methods.

Parameters:
url The base uri used in all request

+ (void) setBasicAuthWithUsername: (NSString *)  username
password: (NSString *)  password 

Set the username and password used in requests that require basic authentication.

The username and password privded here will be Base64 encoded and sent as an Authorization header.

Parameters:
username user name used to authenticate
password Password used to authenticate

+ (void) setDefaultParams: (NSDictionary *)  params  

Set the defaul params sent with every request. If you need to send something with every request this is the perfect way to do it. For GET request, these parameters will be appended to the query string. For POST request these parameters are sent with the body.

+ (void) setDelegate: (NSObject *)  del  

Set the HRResponseDelegate

Parameters:
del The HRResponseDelegate responsible for handling callbacks

+ (void) setFormat: (HRDataFormat)  format  

Set the format used to decode and encode request and responses.

+ (void) setHeaders: (NSDictionary *)  hdrs  

Set the default headers sent with every request.

Parameters:
hdrs An NSDictionary of headers. For example you can set this up.
 NSDictionary *hdrs = [NSDictionary dictionaryWithObject:@"application/json" forKey:@"Accept"];
 [self setHeaders:hdrs];

The documentation for this class was generated from the following files: