The alamofire from ashfurrow

Alamofire is an HTTP networking library written in Swift. Think of it as AFNetworking, reimagined for the conventions of this new language.

Of course, AFNetworking remains the premiere networking library available for Mac OS X and iOS, and can easily be used in Swift, just like any other Objective-C code. AFNetworking is stable and reliable, and isn't going anywhere. But for anyone looking for something a little more idiomatic to Swift, Alamofire may be right up your alley. (It's not a mutually-exclusive choice, either! AFNetworking & Alamofire will peacefully co-exist within the same codebase.)

Alamofire is named after the Alamo Fire flower, a hybrid variant of the Bluebonnet, the official state flower of Texas.

Features

Chainable Request / Response methods
URL / JSON / plist Parameter Encoding
Upload File / Data / Stream
Download using Request or Resume data
Authentication with NSURLCredential
Progress Closure & NSProgress
cURL Debug Output

Planned for 1.0 Release*

* Scheduled to coincide with Swift 1.0 release

100% Unit Test Coverage
Complete Documentation
HTTP Response Validation
TLS Chain Validation
UIKit / AppKit Extensions

Requirements

Xcode 6
iOS 7.0+ / Mac OS X 10.9+

Installation

The infrastructure and best practices for distributing Swift libraries is currently being developed by the developer community during this beta period of the language and Xcode. In the meantime, you can simply add Alamofire as a git submodule, and drag the Alamofire.swift file into your Xcode project.

Usage

GET Request

Alamofire.request(.GET, "http://httpbin.org/get")

With Parameters

Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])

With Response Handling

Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])
         .response { (request, response, data, error) in
                     println(request)
                     println(response)
                     println(error)
                   }

With Response String Handling

Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])
         .responseString { (request, response, string, error) in
                  println(string)
         }

HTTP Methods

The Alamofire.Method enum lists the HTTP methods defined in RFC 2616 §9:

public enum Method: String {
    case OPTIONS = "OPTIONS"
    case GET = "GET"
    case HEAD = "HEAD"
    case POST = "POST"
    case PUT = "PUT"
    case PATCH = "PATCH"
    case DELETE = "DELETE"
    case TRACE = "TRACE"
    case CONNECT = "CONNECT"
}

These values can be passed as the first argument of the Alamofire.request method:

Alamofire.request(.POST, "http://httpbin.org/post")

Alamofire.request(.PUT, "http://httpbin.org/put")

Alamofire.request(.DELETE, "http://httpbin.org/delete")

POST Request

let parameters = [
    "foo": "bar",
    "baz": ["a", 1],
    "qux": [
        "x": 1,
        "y": 2,
        "z": 3
    ]
]

Alamofire.request(.POST, "http://httpbin.org/post", parameters: parameters)

This sends the following HTTP Body:

foo=bar&baz[]=a&baz[]=1&qux[x]=1&qux[y]=2&qux[z]=3

Alamofire has built-in support for encoding parameters as URL query / URI form encoded, JSON, and Property List, using the Alamofire.ParameterEncoding enum:

Parameter Encoding

enum ParameterEncoding {
    case URL
    case JSON(options: NSJSONWritingOptions)
    case PropertyList(format: NSPropertyListFormat,
                      options: NSPropertyListWriteOptions)

    func encode(request: NSURLRequest,
                parameters: [String: AnyObject]?) ->
                    (NSURLRequest, NSError?)
    { ... }
}

Manual Parameter Encoding of an NSURLRequest

let URL = NSURL(string: "http://httpbin.org/get")
var request = NSURLRequest(URL: URL)

let parameters = ["foo": "bar"]
let encoding = Alamofire.ParameterEncoding.URL
(request, _) = encoding.encode(request, parameters)

POST Request with JSON Response

Alamofire.request(.POST, "http://httpbin.org/post", parameters: parameters, encoding: .JSON(options: nil))
         .responseJSON {(request, response, JSON, error) in
            println(JSON)
         }

Built-In Response Methods

response()
responseString(encoding: NSStringEncoding)
responseJSON(options: NSJSONReadingOptions)
responsePropertyList(options: NSPropertyListReadOptions)

Uploading

Supported Upload Types

File
Data
Stream
Multipart (Coming Soon)

Uploading a File

let fileURL = NSBundle.mainBundle()
                      .URLForResource("Default",
                                      withExtension: "png")

Alamofire.upload(.POST, "http://httpbin.org/post", file: fileURL)

Uploading w/Progress

Alamofire.upload(.POST, "http://httpbin.org/post", file: fileURL)
        .progress { (bytesWritten, totalBytesWritten, totalBytesExpectedToWrite) in
            println(totalBytesWritten)
        }
        .responseJSON { (request, response, JSON, error) in
            println(JSON)
        }

Downloading

Supported Download Types

Request
Resume Data

Downloading a File

Alamofire.download(.GET, "http://httpbin.org/stream/100", destination: { (temporaryURL, response) in
    if let directoryURL = NSFileManager.defaultManager()
                          .URLsForDirectory(.DocumentDirectory,
                                            inDomains: .UserDomainMask)[0]
                          as? NSURL {
        let pathComponent = response.suggestedFilename

        return directoryURL.URLByAppendingPathComponent(pathComponent)
    }

    return temporaryURL
})

Using the Default Download Destination Closure Function

let destination = Alamofire.Request.suggestedDownloadDestination(directory: .DocumentDirectory, domain: .UserDomainMask)

Alamofire.download(.GET, "http://httpbin.org/stream/100", destination: destination)

Downloading a File w/Progress

Alamofire.download(.GET, "http://httpbin.org/stream/100", destination: destination)
         .progress { (bytesRead, totalBytesRead, totalBytesExpectedToRead) in
             println(totalBytesRead)
         }
         .response { (request, response, _, error) in
             println(response)
         }

Authentication

Supported Authentication Schemes

HTTP Basic
HTTP Digest
Kerberos
NTLM

HTTP Basic Authentication

let user = "user"
let password = "password"

Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(user)/\(password)")
    .authenticate(HTTPBasic: user, password: password)
    .response {(request, response, _, error) in
        println(response)
    }

Authenticating with NSURLCredential & NSURLProtectionSpace

let user = "user"
let password = "password"

let credential = NSURLCredential(user: user, password: password, persistence: .ForSession)
let protectionSpace = NSURLProtectionSpace(host: "httpbin.org", port: 0, `protocol`: "https", realm: nil, authenticationMethod: NSURLAuthenticationMethodHTTPBasic)

Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(user)/\(password)")
    .authenticate(usingCredential: credential, forProtectionSpace: protectionSpace)
    .response {(request, response, _, error) in
        println(response)
}

Printable

let request = Alamofire.request(.GET, "http://httpbin.org/ip")

println(request)
// GET http://httpbin.org/ip (200)

DebugPrintable

let request = Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])

debugPrintln(request)

Output (cURL)

$ curl -i \
	-H "User-Agent: Alamofire" \
	-H "Accept-Encoding: Accept-Encoding: gzip;q=1.0,compress;q=0.5" \
	-H "Accept-Language: en;q=1.0,fr;q=0.9,de;q=0.8,zh-Hans;q=0.7,zh-Hant;q=0.6,ja;q=0.5" \
	"http://httpbin.org/get?foo=bar"

typealias

typealias AF = Alamofire

AF.request(.GET, "http://httpbin.org/ip")

More Complex Use Cases

Much of the functionality described above is provided as a convenience API on top of something more extensible, closer to the Foundation URL Loading System. For more complex usage, such as creating a NSURLSession with a custom configuration or passing NSURLRequest objects directly, Alamofire provides API that can accommodate that.

See the implementation of the Alamofire.Manager and Alamofire.Request classes for details on what's possible. Documentation and additional API refinement are forthcoming in future releases.

Contact

Follow AFNetworking on Twitter (@AFNetworking)

Creator

Mattt Thompson (@mattt)

License

Alamofire is released under an MIT license. See LICENSE for more information.

ashfurrow / alamofire Goto Github PK

alamofire's Introduction