Obj-C / Cocoa HTTP requests for humans
Objective-C Other Other
Latest commit c9446f3 Aug 18, 2016 @nst nst preparing release 1.1.3



A NSURLSession wrapper for humans

  • 1000 lines of Objective-C you can understand
  • runs on iOS 7+ 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
Typical usage


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

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

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

[r startAsynchronous];


let r = STHTTPRequest(URLString:"http://www.google.com")

r.completionBlock = { (headers, body) in
    // ...

r.errorBlock = { (error) in
    // ...



  • 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"];
set the GET parameters
r.GETDictionary = @{ @"paperid":@"6", @"q77":"1", @"q80":@"hello" };
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
    Cookie = asd=sdf; xxx=yyy
    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" \

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


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

BSD 3-Clause License

See LICENCE.txt.