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

You can fill a queue with fake responses to be consumed by requests started from unit tests.

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.