![](\"http:\/\/raw.githubusercontent.com\/Alamofire\/Alamofire\/assets\/alamofire.png\")
<\/p>\n<\/p>\n
Alamofire is an HTTP networking library written in Swift.<\/p>\n
\nEmbedded frameworks require a minimum deployment target of iOS 8 or OS X Mavericks.<\/strong><\/p>\n
To use Alamofire with a project targeting iOS 7, you must include all Swift files located inside the
Source<\/code> directory directly in your project. See the \u2018Source File\u2019 section for additional instructions.<\/p>\n<\/blockquote>\nCocoaPods<\/h3>\n
CocoaPods is a dependency manager for Cocoa projects.<\/p>\n
CocoaPods 0.36 adds supports for Swift and embedded frameworks. You can install it with the following command:<\/p>\n
$ gem install cocoapods\n<\/code><\/pre>\nTo integrate Alamofire into your Xcode project using CocoaPods, specify it in your
Podfile<\/code>:<\/p>\nsource 'https:\/\/github.com\/CocoaPods\/Specs.git'\nplatform :ios, '8.0'\nuse_frameworks!\n\npod 'Alamofire', '~> 1.2'\n<\/code><\/pre>\nThen, run the following command:<\/p>\n
$ pod install\n<\/code><\/pre>\nCarthage<\/h3>\n
Carthage is a decentralized dependency manager that automates the process of adding frameworks to your Cocoa application.<\/p>\n
You can install Carthage with Homebrew using the following command:<\/p>\n
$ brew update\n$ brew install carthage\n<\/code><\/pre>\nTo integrate Alamofire into your Xcode project using Carthage, specify it in your
Cartfile<\/code>:<\/p>\ngithub \"Alamofire\/Alamofire\" >= 1.2\n<\/code><\/pre>\nManually<\/h3>\n
If you prefer not to use either of the aforementioned dependency managers, you can integrate Alamofire into your project manually.<\/p>\n
Embedded Framework<\/h4>\n
\n
- Add Alamofire as a submodule by opening the Terminal,
cd<\/code>-ing into your top-level project directory, and entering the following command:<\/li>\n<\/ul>\n$ git submodule add https:\/\/github.com\/Alamofire\/Alamofire.git\n<\/code><\/pre>\n\n
- \n
Open the new
Alamofire<\/code> folder, and drag theAlamofire.xcodeproj<\/code> into the Project Navigator of your application\u2019s Xcode project.<\/p>\n\nIt should appear nested underneath your application\u2019s blue project icon. Whether it is above or below all the other Xcode groups does not matter.<\/p>\n<\/blockquote>\n<\/li>\n
- \n
Select the
Alamofire.xcodeproj<\/code> in the Project Navigator and verify the deployment target matches that of your application target.<\/p>\n<\/li>\n- \n
Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the \u201cTargets\u201d heading in the sidebar.<\/p>\n<\/li>\n
- \n
In the tab bar at the top of that window, open the \u201cGeneral\u201d panel.<\/p>\n<\/li>\n
- \n
Click on the
+<\/code> button under the \u201cEmbedded Binaries\u201d section.<\/p>\n<\/li>\n- \n
You will see two different
Alamofire.xcodeproj<\/code> folders each with two different versions of theAlamofire.framework<\/code> nested inside aProducts<\/code> folder.<\/p>\n\nIt does not matter which
Products<\/code> folder you choose from, but it does matter whether you choose the top or bottomAlamofire.framework<\/code>.<\/p>\n<\/blockquote>\n<\/li>\n- \n
Select the top
Alamofire.framework<\/code> for iOS and the bottom one for OS X.<\/p>\n\nYou can verify which one you selected by inspecting the build log for your project. The build target for
Alamofire<\/code> will be listed as eitherAlamofire iOS<\/code> orAlamofire OSX<\/code>.<\/p>\n<\/blockquote>\n<\/li>\n- \n
And that\u2019s it!<\/p>\n<\/li>\n<\/ul>\n
\nThe
Alamofire.framework<\/code> is automagically added as a target dependency, linked framework and embedded framework in a copy files build phase which is all you need to build on the simulator and a device.<\/p>\n<\/blockquote>\nSource File<\/h4>\n
For application targets that do not support embedded frameworks, such as iOS 7, Alamofire can be integrated by adding all the Swift files located inside the
Source<\/code> directory (Source\/*.swift<\/code>) directly into your project. Note that you will no longer need toimport Alamofire<\/code> since you are not actually loading a framework. Additionally, any of the calling conventions described in the \u2018Usage\u2019 section with theAlamofire<\/code> prefix would instead omit it (for example,Alamofire.request<\/code> becomesrequest<\/code>), since this functionality is incorporated into the top-level namespace.<\/p>\nUsage<\/h2>\n
Making a Request<\/h3>\n
import Alamofire\n\nAlamofire.request(.GET, \"http:\/\/httpbin.org\/get\")\n<\/code><\/pre>\nResponse Handling<\/h3>\n
Alamofire.request(.GET, \"http:\/\/httpbin.org\/get\", parameters: [\"foo\": \"bar\"])\n .response { (request, response, data, error) in\n println(request)\n println(response)\n println(error)\n }\n<\/code><\/pre>\n\nNetworking in Alamofire is done asynchronously<\/em>. Asynchronous programming may be a source of frustration to programmers unfamiliar with the concept, but there are very good reasons for doing it this way.<\/p>\n<\/blockquote>\n
\nRather than blocking execution to wait for a response from the server, a callback is specified to handle the response once it\u2019s received. The result of a request is only available inside the scope of a response handler. Any execution contingent on the response or data received from the server must be done within a handler.<\/p>\n<\/blockquote>\n
Response Serialization<\/h3>\n
Built-in Response Methods<\/strong><\/p>\n
\n
response()<\/code><\/li>\nresponseString(encoding: NSStringEncoding)<\/code><\/li>\nresponseJSON(options: NSJSONReadingOptions)<\/code><\/li>\nresponsePropertyList(options: NSPropertyListReadOptions)<\/code><\/li>\n<\/ul>\nResponse String Handler<\/h4>\n
Alamofire.request(.GET, \"http:\/\/httpbin.org\/get\")\n .responseString { (_, _, string, _) in\n println(string)\n }\n<\/code><\/pre>\nResponse JSON Handler<\/h4>\n
Alamofire.request(.GET, \"http:\/\/httpbin.org\/get\")\n .responseJSON { (_, _, JSON, _) in\n println(JSON)\n }\n<\/code><\/pre>\nChained Response Handlers<\/h4>\n
Response handlers can even be chained:<\/p>\n
Alamofire.request(.GET, \"http:\/\/httpbin.org\/get\")\n .responseString { (_, _, string, _) in\n println(string)\n }\n .responseJSON { (_, _, JSON, _) in\n println(JSON)\n }\n<\/code><\/pre>\nHTTP Methods<\/h3>\n
Alamofire.Method<\/code> lists the HTTP methods defined in RFC 7231 \u00a74.3:<\/p>\npublic enum Method: String {\n case OPTIONS = \"OPTIONS\"\n case GET = \"GET\"\n case HEAD = \"HEAD\"\n case POST = \"POST\"\n case PUT = \"PUT\"\n case PATCH = \"PATCH\"\n case DELETE = \"DELETE\"\n case TRACE = \"TRACE\"\n case CONNECT = \"CONNECT\"\n}\n<\/code><\/pre>\nThese values can be passed as the first argument of the
Alamofire.request<\/code> method:<\/p>\nAlamofire.request(.POST, \"http:\/\/httpbin.org\/post\")\n\nAlamofire.request(.PUT, \"http:\/\/httpbin.org\/put\")\n\nAlamofire.request(.DELETE, \"http:\/\/httpbin.org\/delete\")\n<\/code><\/pre>\nParameters<\/h3>\n
GET Request With URL-Encoded Parameters<\/h4>\n
Alamofire.request(.GET, \"http:\/\/httpbin.org\/get\", parameters: [\"foo\": \"bar\"])\n\/\/ http:\/\/httpbin.org\/get?foo=bar\n<\/code><\/pre>\nPOST Request With URL-Encoded Parameters<\/h4>\n
let parameters = [\n \"foo\": \"bar\",\n \"baz\": [\"a\", 1],\n \"qux\": [\n \"x\": 1,\n \"y\": 2,\n \"z\": 3\n ]\n]\n\nAlamofire.request(.POST, \"http:\/\/httpbin.org\/post\", parameters: parameters)\n\/\/ HTTP body: foo=bar&baz[]=a&baz[]=1&qux[x]=1&qux[y]=2&qux[z]=3\n<\/code><\/pre>\nParameter Encoding<\/h3>\n
Parameters can also be encoded as JSON, Property List, or any custom format, using the
ParameterEncoding<\/code> enum:<\/p>\nenum ParameterEncoding {\n case URL\n case JSON\n case PropertyList(format: NSPropertyListFormat,\n options: NSPropertyListWriteOptions)\n\n func encode(request: NSURLRequest,\n parameters: [String: AnyObject]?) ->\n (NSURLRequest, NSError?)\n { ... }\n}\n<\/code><\/pre>\n\n
URL<\/code>: A query string to be set as or appended to any existing URL query forGET<\/code>,HEAD<\/code>, andDELETE<\/code> requests, or set as the body for requests with any other HTTP method. TheContent-Type<\/code> HTTP header field of an encoded request with HTTP body is set toapplication\/x-www-form-urlencoded<\/code>. Since there is no published specification for how to encode collection types, Alamofire follows the convention of appending[]<\/code> to the key for array values (foo[]=1&foo[]=2<\/code>), and appending the key surrounded by square brackets for nested dictionary values (foo[bar]=baz<\/code>).<\/em><\/li>\nJSON<\/code>: UsesNSJSONSerialization<\/code> to create a JSON representation of the parameters object, which is set as the body of the request. TheContent-Type<\/code> HTTP header field of an encoded request is set toapplication\/json<\/code>.<\/li>\nPropertyList<\/code>: UsesNSPropertyListSerialization<\/code> to create a plist representation of the parameters object, according to the associated format and write options values, which is set as the body of the request. TheContent-Type<\/code> HTTP header field of an encoded request is set toapplication\/x-plist<\/code>.<\/li>\nCustom<\/code>: Uses the associated closure value to construct a new request given an existing request and parameters.<\/li>\n<\/ul>\nManual Parameter Encoding of an NSURLRequest<\/h4>\n
let URL = NSURL(string: \"http:\/\/httpbin.org\/get\")!\nvar request = NSURLRequest(URL: URL)\n\nlet parameters = [\"foo\": \"bar\"]\nlet encoding = Alamofire.ParameterEncoding.URL\n(request, _) = encoding.encode(request, parameters: parameters)\n<\/code><\/pre>\nPOST Request with JSON-encoded Parameters<\/h4>\n
let parameters = [\n \"foo\": [1,2,3],\n \"bar\": [\n \"baz\": \"qux\"\n ]\n]\n\nAlamofire.request(.POST, \"http:\/\/httpbin.org\/post\", parameters: parameters, encoding: .JSON)\n\/\/ HTTP body: {\"foo\": [1, 2, 3], \"bar\": {\"baz\": \"qux\"}}\n<\/code><\/pre>\nCaching<\/h3>\n
Caching is handled on the system framework level by
NSURLCache<\/code>.<\/p>\nUploading<\/h3>\n
Supported Upload Types<\/strong><\/p>\n
Uploading a File<\/h4>\n
let fileURL = NSBundle.mainBundle()\n .URLForResource(\"Default\",\n withExtension: \"png\")\n\nAlamofire.upload(.POST, \"http:\/\/httpbin.org\/post\", file: fileURL)\n<\/code><\/pre>\nUploading w\/Progress<\/h4>\n
Alamofire.upload(.POST, \"http:\/\/httpbin.org\/post\", file: fileURL)\n .progress { (bytesWritten, totalBytesWritten, totalBytesExpectedToWrite) in\n println(totalBytesWritten)\n }\n .responseJSON { (request, response, JSON, error) in\n println(JSON)\n }\n<\/code><\/pre>\nDownloading<\/h3>\n
Supported Download Types<\/strong><\/p>\n
Downloading a File<\/h4>\n
Alamofire.download(.GET, \"http:\/\/httpbin.org\/stream\/100\", destination: { (temporaryURL, response) in\n if let directoryURL = NSFileManager.defaultManager()\n .URLsForDirectory(.DocumentDirectory,\n inDomains: .UserDomainMask)[0]\n as? NSURL {\n let pathComponent = response.suggestedFilename\n\n return directoryURL.URLByAppendingPathComponent(pathComponent!)\n }\n\n return temporaryURL\n})\n<\/code><\/pre>\nUsing the Default Download Destination<\/h4>\n
let destination = Alamofire.Request.suggestedDownloadDestination(directory: .DocumentDirectory, domain: .UserDomainMask)\n\nAlamofire.download(.GET, \"http:\/\/httpbin.org\/stream\/100\", destination: destination)\n<\/code><\/pre>\nDownloading a File w\/Progress<\/h4>\n
Alamofire.download(.GET, \"http:\/\/httpbin.org\/stream\/100\", destination: destination)\n .progress { (bytesRead, totalBytesRead, totalBytesExpectedToRead) in\n println(totalBytesRead)\n }\n .response { (request, response, _, error) in\n println(response)\n }\n<\/code><\/pre>\nAuthentication<\/h3>\n
Authentication is handled on the system framework level by
NSURLCredential<\/code> andNSURLAuthenticationChallenge<\/code>.<\/p>\nSupported Authentication Schemes<\/strong><\/p>\n
\n
- HTTP Basic<\/li>\n
- HTTP Digest<\/li>\n
- Kerberos<\/li>\n
- NTLM<\/li>\n<\/ul>\n
HTTP Basic Authentication<\/h4>\n
let user = \"user\"\nlet password = \"password\"\n\nAlamofire.request(.GET, \"https:\/\/httpbin.org\/basic-auth\/\\(user)\/\\(password)\")\n .authenticate(user: user, password: password)\n .response {(request, response, _, error) in\n println(response)\n }\n<\/code><\/pre>\nAuthentication with NSURLCredential<\/h4>\n
let user = \"user\"\nlet password = \"password\"\n\nlet credential = NSURLCredential(user: user, password: password, persistence: .ForSession)\n\nAlamofire.request(.GET, \"https:\/\/httpbin.org\/basic-auth\/\\(user)\/\\(password)\")\n .authenticate(usingCredential: credential)\n .response {(request, response, _, error) in\n println(response)\n }\n<\/code><\/pre>\nValidation<\/h3>\n
By default, Alamofire treats any completed request to be successful, regardless of the content of the response. Calling
validate<\/code> before a response handler causes an error to be generated if the response had an unacceptable status code or MIME type.<\/p>\nManual Validation<\/h4>\n
Alamofire.request(.GET, \"http:\/\/httpbin.org\/get\", parameters: [\"foo\": \"bar\"])\n .validate(statusCode: 200.. Serializer {\n return { (request, response, data) in\n if data == nil {\n return (nil, nil)\n }\n\n var XMLSerializationError: NSError?\n let XML = ONOXMLDocument(data: data, &XMLSerializationError)\n\n return (XML, XMLSerializationError)\n }\n }\n\n func responseXMLDocument(completionHandler: (NSURLRequest, NSHTTPURLResponse?, ONOXMLDocument?, NSError?) -> Void) -> Self {\n return response(serializer: Request.XMLResponseSerializer(), completionHandler: { (request, response, XML, error) in\n completionHandler(request, response, XML as? ONOXMLDocument, error)\n })\n }\n}\n<\/code><\/pre>\nGeneric Response Object Serialization<\/h4>\n
Generics can be used to provide automatic, type-safe response object serialization.<\/p>\n
@objc public protocol ResponseObjectSerializable {\n init?(response: NSHTTPURLResponse, representation: AnyObject)\n}\n\nextension Alamofire.Request {\n public func responseObject(completionHandler: (NSURLRequest, NSHTTPURLResponse?, T?, NSError?) -> Void) -> Self {\n let serializer: Serializer = { (request, response, data) in\n let JSONSerializer = Request.JSONResponseSerializer(options: .AllowFragments)\n let (JSON: AnyObject?, serializationError) = JSONSerializer(request, response, data)\n if response != nil && JSON != nil {\n return (T(response: response!, representation: JSON!), nil)\n } else {\n return (nil, serializationError)\n }\n }\n\n return response(serializer: serializer, completionHandler: { (request, response, object, error) in\n completionHandler(request, response, object as? T, error)\n })\n }\n}\n<\/code><\/pre>\nfinal class User: ResponseObjectSerializable {\n let username: String\n let name: String\n\n required init?(response: NSHTTPURLResponse, representation: AnyObject) {\n self.username = response.URL!.lastPathComponent\n self.name = representation.valueForKeyPath(\"name\") as String\n }\n}\n<\/code><\/pre>\nAlamofire.request(.GET, \"http:\/\/example.com\/users\/mattt\")\n .responseObject { (_, _, user: User?, _) in\n println(user)\n }\n<\/code><\/pre>\nThe same approach can also be used to handle endpoints that return a representation of a collection of objects:<\/p>\n
@objc public protocol ResponseCollectionSerializable {\n class func collection(#response: NSHTTPURLResponse, representation: AnyObject) -> [Self]\n}\n\nextension Alamofire.Request {\n public func responseCollection(completionHandler: (NSURLRequest, NSHTTPURLResponse?, [T]?, NSError?) -> Void) -> Self {\n let serializer: Serializer = { (request, response, data) in\n let JSONSerializer = Request.JSONResponseSerializer(options: .AllowFragments)\n let (JSON: AnyObject?, serializationError) = JSONSerializer(request, response, data)\n if response != nil && JSON != nil {\n return (T.collection(response: response!, representation: JSON!), nil)\n } else {\n return (nil, serializationError)\n }\n }\n\n return response(serializer: serializer, completionHandler: { (request, response, object, error) in\n completionHandler(request, response, object as? [T], error)\n })\n }\n}\n<\/code><\/pre>\nURLStringConvertible<\/h3>\n
Types adopting the
URLStringConvertible<\/code> protocol can be used to construct URL strings, which are then used to construct URL requests.NSString<\/code>,NSURL<\/code>,NSURLComponents<\/code>, andNSURLRequest<\/code> conform toURLStringConvertible<\/code> by default, allowing any of them to be passed asURLString<\/code> parameters to therequest<\/code>,upload<\/code>, anddownload<\/code> methods:<\/p>\nlet string = NSString(string: \"http:\/\/httpbin.org\/post\")\nAlamofire.request(.POST, string)\n\nlet URL = NSURL(string: string)!\nAlamofire.request(.POST, URL)\n\nlet URLRequest = NSURLRequest(URL: URL)\nAlamofire.request(.POST, URLRequest) \/\/ overrides `HTTPMethod` of `URLRequest`\n\nlet URLComponents = NSURLComponents(URL: URL, resolvingAgainstBaseURL: true)\nAlamofire.request(.POST, URLComponents)\n<\/code><\/pre>\nApplications interacting with web applications in a significant manner are encouraged to have custom types conform to
URLStringConvertible<\/code> as a convenient way to map domain-specific models to server resources.<\/p>\nType-Safe Routing<\/h4>\n
extension User: URLStringConvertible {\n static let baseURLString = \"http:\/\/example.com\"\n\n var URLString: String {\n return User.baseURLString + \"\/users\/\\(username)\/\"\n }\n}\n<\/code><\/pre>\nlet user = User(username: \"mattt\")\nAlamofire.request(.GET, user) \/\/ http:\/\/example.com\/users\/mattt\n<\/code><\/pre>\nURLRequestConvertible<\/h3>\n
Types adopting the
URLRequestConvertible<\/code> protocol can be used to construct URL requests.NSURLRequest<\/code> conforms toURLRequestConvertible<\/code> by default, allowing it to be passed intorequest<\/code>,upload<\/code>, anddownload<\/code> methods directly (this is the recommended way to specify custom HTTP header fields or HTTP body for individual requests):<\/p>\nlet URL = NSURL(string: \"http:\/\/httpbin.org\/post\")!\nlet mutableURLRequest = NSMutableURLRequest(URL: URL)\nmutableURLRequest.HTTPMethod = \"POST\"\n\nlet parameters = [\"foo\": \"bar\"]\nvar JSONSerializationError: NSError? = nil\nmutableURLRequest.HTTPBody = NSJSONSerialization.dataWithJSONObject(parameters, options: nil, error: &JSONSerializationError)\nmutableURLRequest.setValue(\"application\/json\", forHTTPHeaderField: \"Content-Type\")\n\nAlamofire.request(mutableURLRequest)\n<\/code><\/pre>\nApplications interacting with web applications in a significant manner are encouraged to have custom types conform to
URLRequestConvertible<\/code> as a way to ensure consistency of requested endpoints. Such an approach can be used to abstract away server-side inconsistencies and provide type-safe routing, as well as manage authentication credentials and other state.<\/p>\nAPI Parameter Abstraction<\/h4>\n
enum Router: URLRequestConvertible {\n static let baseURLString = \"http:\/\/example.com\"\n static let perPage = 50\n\n case Search(query: String, page: Int)\n\n \/\/ MARK: URLRequestConvertible\n\n var URLRequest: NSURLRequest {\n let (path: String, parameters: [String: AnyObject]?) = {\n switch self {\n case .Search(let query, let page) where page > 1:\n return (\"\/search\", [\"q\": query, \"offset\": Router.perPage * page])\n case .Search(let query, _):\n return (\"\/search\", [\"q\": query])\n }\n }()\n\n let URL = NSURL(string: Router.baseURLString)!\n let URLRequest = NSURLRequest(URL: URL.URLByAppendingPathComponent(path))\n let encoding = Alamofire.ParameterEncoding.URL\n\n return encoding.encode(URLRequest, parameters: parameters).0\n }\n}\n<\/code><\/pre>\nAlamofire.request(Router.Search(query: \"foo bar\", page: 1)) \/\/ ?q=foo+bar&offset=50\n<\/code><\/pre>\nCRUD & Authorization<\/h4>\n
enum Router: URLRequestConvertible {\n static let baseURLString = \"http:\/\/example.com\"\n static var OAuthToken: String?\n\n case CreateUser([String: AnyObject])\n case ReadUser(String)\n case UpdateUser(String, [String: AnyObject])\n case DestroyUser(String)\n\n var method: Alamofire.Method {\n switch self {\n case .CreateUser:\n return .POST\n case .ReadUser:\n return .GET\n case .UpdateUser:\n return .PUT\n case .DestroyUser:\n return .DELETE\n }\n }\n\n var path: String {\n switch self {\n case .CreateUser:\n return \"\/users\"\n case .ReadUser(let username):\n return \"\/users\/\\(username)\"\n case .UpdateUser(let username, _):\n return \"\/users\/\\(username)\"\n case .DestroyUser(let username):\n return \"\/users\/\\(username)\"\n }\n }\n\n \/\/ MARK: URLRequestConvertible\n\n var URLRequest: NSURLRequest {\n let URL = NSURL(string: Router.baseURLString)!\n let mutableURLRequest = NSMutableURLRequest(URL: URL.URLByAppendingPathComponent(path))\n mutableURLRequest.HTTPMethod = method.rawValue\n\n if let token = Router.OAuthToken {\n mutableURLRequest.setValue(\"Bearer \\(token)\", forHTTPHeaderField: \"Authorization\")\n }\n\n switch self {\n case .CreateUser(let parameters):\n return Alamofire.ParameterEncoding.JSON.encode(mutableURLRequest, parameters: parameters).0\n case .UpdateUser(_, let parameters):\n return Alamofire.ParameterEncoding.URL.encode(mutableURLRequest, parameters: parameters).0\n default:\n return mutableURLRequest\n }\n }\n}\n<\/code><\/pre>\nAlamofire.request(Router.ReadUser(\"mattt\")) \/\/ GET \/users\/mattt\n<\/code><\/pre>\nFAQ<\/h2>\n
When should I use Alamofire?<\/h3>\n
If you\u2019re starting a new project in Swift, and want to take full advantage of its conventions and language features, Alamofire is a great choice. Although not as fully-featured as AFNetworking, Alamofire is much nicer to work with, and should satisfy the vast majority of networking use cases.<\/p>\n
\nIt\u2019s important to note that two libraries aren\u2019t mutually exclusive: AFNetworking and Alamofire can peacefully exist in the same code base.<\/p>\n<\/blockquote>\n
When should I use AFNetworking?<\/h3>\n
AFNetworking remains the premiere networking library available for 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\u2019t going anywhere.<\/p>\n
Use AFNetworking for any of the following:<\/p>\n
\n
- UIKit extensions, such as asynchronously loading images to