free1990 / sthttprequest

A NSURLConnection wrapper for humans

STHTTPRequest

A NSURLConnection wrapper for humans

Simple...

• 900 lines of Objective-C you can understand
• runs on iOS 5+ and Mac OS X 10.7+
• just drag and drop .h and .m in your project
• pod 'STHTTPRequest' in CocoaPods
• new BSD license

... yet powerful

• synchronous and asynchronous (block based) calls
• easy to set request headers, cookies and POST data
• easy to get response status, headers and encoding
• file upload with progress block
• can use streaming with the download progress block
• fast and simple HTTP authentication
• log requests in curl format

Maturity

STHTTPRequest is used in many applications available on the App Store and used by 100'000+ regular users.

STHTTPRequest is also used in the STTwitter library, the main Objective-C library to access Twitter API.

Typical usage

STHTTPRequest *r = [STHTTPRequest requestWithURLString:@"http://google.com"];

r.completionBlock = ^(NSDictionary *headers, NSString *body) {
    // ...
};

r.errorBlock = ^(NSError *error) {
    // ...
};

[r startAsynchronous];

Notes:

• STHTTPRequest must be used from the main thread
• all blocks are guaranteed to be called on main thread

Start a synchronous request

NSError *error = nil;
NSString *body = [r startSynchronousWithError:&error];

Get HTTP data and metadata

NSInteger     status   = r.responseStatus;
NSDictionary *headers  = r.responseHeaders;
NSString     *encoding = r.responseStringEncodingName;
NSData       *data     = r.responseData;

Add a request header

[r setHeaderWithName:@"test" value:@"1234"];

Add a request cookie

[r addCookieWithName:@"test" value:@"1234"];

Set credentials

[r setUsername:@"test" password:@"1234"];

POST a dictionary

r.POSTDictionary = @{ @"paperid":@"6", @"q77":"1", @"q80":@"hello" };

POST raw data

request.rawPOSTData = myData;

full example here

Upload a file

[r addFileToUpload:@"/tmp/photo.jpg" parameterName:@"photo"];

full example here

Upload an image and set parameters

NSData *imageData = [NSData dataWithContentsOfFile:"image.jpg"];
[request addDataToUpload:imageData parameterName:@"param" mimeType:@"image/jpeg" fileName:@"file_name"];

Upload several images

[request addDataToUpload:data1 parameterName:@"p1" mimeType:@"image/jpeg" fileName:@"name1"];
[request addDataToUpload:data2 parameterName:@"p2" mimeType:@"image/jpeg" fileName:@"name2"];

Get headers only

r.HTTPMethod = @"HEAD";

Set a download progress block

r.downloadProgressBlock = ^(NSData *dataJustReceived,
                            NSInteger totalBytesReceived,
                            NSInteger totalBytesExpectedToReceive) {
    // notify user of download progress
    // use the stream
}

Usable in unit tests

The demo project comes with two unit tests target.

AsynchronousTests shows how to perform actual network requests in unit tests.

STHTTPRequestTests show how to perform synchronous tests by filling a queue with fake responses to be consumed by requests started from unit tests. Just include the UnitTestAdditions directory to your project.

Log the requests

To log human readable debug description, add launch argument -STHTTPRequestShowDebugDescription 1.

GET https://raw.github.com/github/media/master/octocats/octocat.png
HEADERS
    Cookie = asd=sdf; xxx=yyy
COOKIES
    asd = sdf
    xxx = yyy

To log curl description, add launch argument -STHTTPRequestShowCurlDescription 1.

$ curl -i \
-b "asd=sdf;xxx=yyy" \
-H "Cookie: asd=sdf; xxx=yyy,asd=sdf; xxx=yyy" \
"https://raw.github.com/github/media/master/octocats/octocat.png"

(Curl is a command-line tool shipped with OS X that can craft HTTP requests.)

Support

If you have any question, open an issue on GitHub or use the STHTTPRequest tag on StackOverflow.

BSD 3-Clause License

See LICENCE.txt.