Cocoa Web Requests
Objective-C Ruby
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
MTPocket.xcodeproj
MTPocket
MTPocketTests
.gitignore
LICENSE
MTPocket.podspec
README.md

README.md

MTPocket

A objective-c networking library that doesn't suck. Setting up network requests can be a pain, so MTPocket lets you define request templates and then you can create requests from those templates anywhere in your application. Cool eh?

Advantages

  • Simple API.
  • Templates.
  • Asynchronous.
  • Request based.
    • Can easily retry a request.
    • Can easily archive a request for sending later with new success/failure callbacks.
  • Success/failure callbacks.
    • You can actually add multiple success/failure callbacks. This is great for building libraries. The library builds a request, adds callback to handle building it's object graph and returns the request to the calling application to add its own callbacks and send the request.
  • Upload/Download progress callbacks.
  • Multi-part form uploads.
  • Awesome URL path building.

Installation

In your Podfile, add this line:

pod "MTPocket"

pod? => https://github.com/CocoaPods/CocoaPods/

NOTE: You may need to add -all_load to "Other Linker Flags" in your targets build settings if the pods library only contains categories.

Example Usage

Set up the base url:

[MTPocket sharedPocket].defaultBaseURL = [NSURL URLWithString:@"http://button.herokuapp.com/"];

A simple request:

MTPocketRequest *request = [MTPocketRequest requestWithPath:@"needles" identifiers:nil method:MTPocketMethodGET body:nil params:nil];
request.format = MTPocketFormatJSON;
[request addHeaders:[MTPocketRequest headerDictionaryForBasicAuthWithUsername:UN password:PW]];
[request sendWithSuccess:^(MTPocketResponse *response) {
    _player.id = response.body[@"id"];
    [self.tableView reloadData];
} failure:^(MTPocketResponse *response) {
    // handle failure...
}];

Create a template:

MTPocketRequest *template = [MTPocketRequest requestTemplate];
template.format = MTPocketFormatJSON;
template.timeout = 2;
[template addHeaders:[MTPocketRequest headerDictionaryForBasicAuthWithUsername:UN password:PW]];
[template.params addEntriesFromDictionary:@{ @"sessionId": @"fewoijalkfsdjlfsdhlaes" }];
[[MTPocket sharedPocket] addRequestTemplate:template name:@"api"];

Create and perform a request with that template:

MTPocketRequest *request = [[MTPocket sharedPocket] requestWithTemplate:@"api" path:@"needles/:id" identifiers:@[ @(identifier) ] method:MTPocketMethodGET body:nil params:nil];
[request sendWithSuccess:^(MTPocketResponse *response) {
    _person.name = respone.body[@"name"];
} failure:^(MTPocketResponse *response) {
    // handle failure...
}];

Monitor upload/download progress:

MTPocketRequest *request = [[MTPocket sharedPocket] requestWithTemplate:@"api" path:@"needles" identifiers:nil method:MTPocketMethodGET body:nil params:nil];
[request sendWithSuccess:^(MTPocketResponse *response) {
    [SVProgressHUD showSuccessWithStatus:@"Downloaded"];
    _file = response.body;
} failure:^(MTPocketResponse *response) {
    [SVProgressHUD showErrorWithStatus:@"Darn"];
} uploadProgress:^(float percent) {
    [SVProgressHUD showProgress:percent];
} downloadProgress:^(float percent) {
    [SVProgressHUD showProgress:percent];
}];

Upload a file as a multipart form:

[request sendFileData:fileData
             filename:@"test.jpg"
            formField:@"files[]"
             MIMEType:@"image/jpeg"
              success:^(MTPocketResponse *resp) {
                  [SVProgressHUD showSuccessWithStatus:@"Uploaded"];
             } failure:^(MTPocketResponse *response) {
                  [SVProgressHUD showErrorWithStatus:@"Darn"];
             } uploadProgress:^(float percent) {
                  [SVProgressHUD showProgress:percent];
             }];

Easily create URL paths with ids (even multiple comma seperated ids):

MTPocketRequest *request = [[MTPocket sharedPocket] requestWithTemplate:@"api" path:@"companies/:company_id/employee/:id" identifiers:@[ @(3), @[ @(2), @(4) ]] method:MTPocketMethodGET body:nil params:nil];
// => @"http://www.example.com/companies/3/employee/2,4"

Screenshots

As you can see, while debugging, MTPocket provides you with a LOT of very useful information about responses from server:

Alt screenshot of debugger in Xcode

Printing the body of the response:

Alt screenshot of console in Xcode

The Request Object

@property (strong,  nonatomic)   NSURL              *baseURL;               // (optional) Will override the default base URL set on the shared pocket singleton

Basic options

@property (strong,  nonatomic)  NSString            *path;                  // (required) The resource path after the base url. Can include placeholders like ':id' that will be filled in respectively with 'identifiers'. e.g. @"buttons/:button_id/stitches/:id"
@property (strong,  nonatomic)  NSArray             *identifiers;           // (required) NSNumber/NSString objects that are swapping it
@property (         nonatomic)  MTPocketMethod      method;                 // (required) Default: MTPocketMethodGET
@property (         nonatomic)  MTPocketFormat      format;                 // (required) Defaut: MTPocketFormatJSON
@property (readonly,nonatomic)  NSMutableDictionary *params;                // (optional) Query string params. @{ @"page" : @(2) } => ?page=2
@property (strong,  nonatomic)  id                  body;                   // (optional) The body of the request. Can be NSData, NSString, NSDictionary, NSArray.

Additional options

@property (readonly,nonatomic)  NSMutableDictionary *headers;               // (optional) The headers dictionary. You can add or delete from the template.
@property (         nonatomic)  NSTimeInterval      timeout;                // (optional) Default: 60 seconds.
@property (strong,  nonatomic)  NSString            *contentLengthHeader;   // (optional) Default: Content-Length. Could also be stream-length, etc. Will be used for progress handlers.

The Response Object

@property (nonatomic, readonly)         BOOL              success;                 // Easily determine if the request was 100% sucessful. Otherwise, lots of data in other properties to deal with the failure.
@property (nonatomic, readonly)         MTPocketStatus    status;                  // A Mapping of common HTTP status codes to enum.
@property (nonatomic, readonly)         MTPocketFormat    format;                  // The format of the original content. Will always be the same as the request format.
@property (nonatomic, readonly, strong) id                body;                    // The response body. Depending on the format, could be an NSString, NSArray, NSDictionary or nil.
@property (nonatomic, readonly, strong) NSError           *error;                  // Could be nil, but should check this for important info if its not nil.
@property (nonatomic, readonly, strong) NSURLRequest      *request;                // The original request made to the server (for debugging).
@property (nonatomic, readonly, strong) MTPocketRequest   *pocketRequest;          // The original request made to the server (for debugging).
@property (nonatomic, readonly, strong) NSData            *data;                   // The data returned form the server (for debugging).
@property (nonatomic, readonly, strong) NSString          *text;                   // The data converted to a string returned form the server (for debugging).
@property (nonatomic, readonly, strong) NSData            *requestData;            // The data that was sent as the body with the request (for debugging).
@property (nonatomic, readonly, strong) NSString          *requestText;            // The data sent with the request converted to a string (for debugging).
@property (nonatomic, readonly, strong) NSDictionary      *requestHeaders;
@property (nonatomic, readonly, strong) NSDictionary      *responseHeaders;
@property (nonatomic, readonly)         NSInteger         statusCode;              // The actual integer status code of the response.
@property (nonatomic, readonly, strong) NSString          *MIMEType;               // What the server reports as the content type of the response.
@property (nonatomic, readonly)         NSInteger         expectedContentLength;   // What the server reports as the expected content length of the response.