Alamofire is an HTTP networking library written in Swift.
- Chainable Request / Response methods
- URL / JSON / plist Parameter Encoding
- Upload File / Data / Stream
- Download using Request or Resume data
- Authentication with NSURLCredential
- HTTP Response Validation
- Progress Closure & NSProgress
- cURL Debug Output
- Comprehensive Unit Test Coverage
- Complete Documentation
- iOS 7.0+ / Mac OS X 10.9+
- Xcode 6.3
- If you need help, use Stack Overflow. (Tag 'alamofire')
- If you'd like to ask a general question, use Stack Overflow.
- If you found a bug, open an issue.
- If you have a feature request, open an issue.
- If you want to contribute, submit a pull request.
Embedded frameworks require a minimum deployment target of iOS 8 or OS X Mavericks.
To use Alamofire with a project targeting iOS 7, you must include all Swift files located inside the
Source
directory directly in your project. See the 'Source File' section for additional instructions.
CocoaPods is a dependency manager for Cocoa projects.
CocoaPods 0.36 adds supports for Swift and embedded frameworks. You can install it with the following command:
$ gem install cocoapods
To integrate Alamofire into your Xcode project using CocoaPods, specify it in your Podfile
:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!
pod 'Alamofire', '~> 1.2'
Then, run the following command:
$ pod install
Carthage is a decentralized dependency manager that automates the process of adding frameworks to your Cocoa application.
You can install Carthage with Homebrew using the following command:
$ brew update
$ brew install carthage
To integrate Alamofire into your Xcode project using Carthage, specify it in your Cartfile
:
github "Alamofire/Alamofire" >= 1.2
If you prefer not to use either of the aforementioned dependency managers, you can integrate Alamofire into your project manually.
- Add Alamofire as a submodule by opening the Terminal,
cd
-ing into your top-level project directory, and entering the following command:
$ git submodule add https://github.com/Alamofire/Alamofire.git
-
Open the new
Alamofire
folder, and drag theAlamofire.xcodeproj
into the Project Navigator of your application's Xcode project.It should appear nested underneath your application's blue project icon. Whether it is above or below all the other Xcode groups does not matter.
-
Select the
Alamofire.xcodeproj
in the Project Navigator and verify the deployment target matches that of your application target. -
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 "Targets" heading in the sidebar.
-
In the tab bar at the top of that window, open the "General" panel.
-
Click on the
+
button under the "Embedded Binaries" section. -
You will see two different
Alamofire.xcodeproj
folders each with two different versions of theAlamofire.framework
nested inside aProducts
folder.It does not matter which
Products
folder you choose from, but it does matter whether you choose the top or bottomAlamofire.framework
. -
Select the top
Alamofire.framework
for iOS and the bottom one for OS X.You can verify which one you selected by inspecting the build log for your project. The build target for
Alamofire
will be listed as eitherAlamofire iOS
orAlamofire OSX
. -
And that's it!
The
Alamofire.framework
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.
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
directory (Source/*.swift
) directly into your project. Note that you will no longer need to import Alamofire
since you are not actually loading a framework. Additionally, any of the calling conventions described in the 'Usage' section with the Alamofire
prefix would instead omit it (for example, Alamofire.request
becomes request
), since this functionality is incorporated into the top-level namespace.
import Alamofire
Alamofire.request(.GET, "http://httpbin.org/get")
Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])
.response { (request, response, data, error) in
println(request)
println(response)
println(error)
}
Networking in Alamofire is done asynchronously. 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.
Rather than blocking execution to wait for a response from the server, a callback is specified to handle the response once it's 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.
Built-in Response Methods
response()
responseString(encoding: NSStringEncoding)
responseJSON(options: NSJSONReadingOptions)
responsePropertyList(options: NSPropertyListReadOptions)
Alamofire.request(.GET, "http://httpbin.org/get")
.responseString { (_, _, string, _) in
println(string)
}
Alamofire.request(.GET, "http://httpbin.org/get")
.responseJSON { (_, _, JSON, _) in
println(JSON)
}
Response handlers can even be chained:
Alamofire.request(.GET, "http://httpbin.org/get")
.responseString { (_, _, string, _) in
println(string)
}
.responseJSON { (_, _, JSON, _) in
println(JSON)
}
Alamofire.Method
lists the HTTP methods defined in RFC 7231 §4.3:
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")
Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])
// http://httpbin.org/get?foo=bar
let parameters = [
"foo": "bar",
"baz": ["a", 1],
"qux": [
"x": 1,
"y": 2,
"z": 3
]
]
Alamofire.request(.POST, "http://httpbin.org/post", parameters: parameters)
// HTTP body: foo=bar&baz[]=a&baz[]=1&qux[x]=1&qux[y]=2&qux[z]=3
Parameters can also be encoded as JSON, Property List, or any custom format, using the ParameterEncoding
enum:
enum ParameterEncoding {
case URL
case JSON
case PropertyList(format: NSPropertyListFormat,
options: NSPropertyListWriteOptions)
func encode(request: NSURLRequest,
parameters: [String: AnyObject]?) ->
(NSURLRequest, NSError?)
{ ... }
}
URL
: A query string to be set as or appended to any existing URL query forGET
,HEAD
, andDELETE
requests, or set as the body for requests with any other HTTP method. TheContent-Type
HTTP header field of an encoded request with HTTP body is set toapplication/x-www-form-urlencoded
. Since there is no published specification for how to encode collection types, Alamofire follows the convention of appending[]
to the key for array values (foo[]=1&foo[]=2
), and appending the key surrounded by square brackets for nested dictionary values (foo[bar]=baz
).JSON
: UsesNSJSONSerialization
to create a JSON representation of the parameters object, which is set as the body of the request. TheContent-Type
HTTP header field of an encoded request is set toapplication/json
.PropertyList
: UsesNSPropertyListSerialization
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
HTTP header field of an encoded request is set toapplication/x-plist
.Custom
: Uses the associated closure value to construct a new request given an existing request and parameters.
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: parameters)
let parameters = [
"foo": [1,2,3],
"bar": [
"baz": "qux"
]
]
Alamofire.request(.POST, "http://httpbin.org/post", parameters: parameters, encoding: .JSON)
// HTTP body: {"foo": [1, 2, 3], "bar": {"baz": "qux"}}
Caching is handled on the system framework level by NSURLCache
.
Supported Upload Types
- File
- Data
- Stream
let fileURL = NSBundle.mainBundle()
.URLForResource("Default",
withExtension: "png")
Alamofire.upload(.POST, "http://httpbin.org/post", file: fileURL)
Alamofire.upload(.POST, "http://httpbin.org/post", file: fileURL)
.progress { (bytesWritten, totalBytesWritten, totalBytesExpectedToWrite) in
println(totalBytesWritten)
}
.responseJSON { (request, response, JSON, error) in
println(JSON)
}
Supported Download Types
- Request
- Resume Data
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
})
let destination = Alamofire.Request.suggestedDownloadDestination(directory: .DocumentDirectory, domain: .UserDomainMask)
Alamofire.download(.GET, "http://httpbin.org/stream/100", destination: destination)
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 is handled on the system framework level by NSURLCredential
and NSURLAuthenticationChallenge
.
Supported Authentication Schemes
let user = "user"
let password = "password"
Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(user)/\(password)")
.authenticate(user: user, password: password)
.response {(request, response, _, error) in
println(response)
}
let user = "user"
let password = "password"
let credential = NSURLCredential(user: user, password: password, persistence: .ForSession)
Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(user)/\(password)")
.authenticate(usingCredential: credential)
.response {(request, response, _, error) in
println(response)
}
By default, Alamofire treats any completed request to be successful, regardless of the content of the response. Calling validate
before a response handler causes an error to be generated if the response had an unacceptable status code or MIME type.
Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])
.validate(statusCode: 200..<300)
.validate(contentType: ["application/json"])
.response { (_, _, _, error) in
println(error)
}
Automatically validates status code within 200...299
range, and that the Content-Type
header of the response matches the Accept
header of the request, if one is provided.
Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])
.validate()
.response { (_, _, _, error) in
println(error)
}
let request = Alamofire.request(.GET, "http://httpbin.org/ip")
println(request)
// GET http://httpbin.org/ip (200)
let request = Alamofire.request(.GET, "http://httpbin.org/get", parameters: ["foo": "bar"])
debugPrintln(request)
$ 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"
Alamofire is built on
NSURLSession
and the Foundation URL Loading System. To make the most of this framework, it is recommended that you be familiar with the concepts and capabilities of the underlying networking stack.
Recommended Reading
- URL Loading System Programming Guide
- NSURLSession Class Reference
- NSURLCache Class Reference
- NSURLAuthenticationChallenge Class Reference
Top-level convenience methods like Alamofire.request
use a shared instance of Alamofire.Manager
, which is configured with the default NSURLSessionConfiguration
.
As such, the following two statements are equivalent:
Alamofire.request(.GET, "http://httpbin.org/get")
let manager = Alamofire.Manager.sharedInstance
manager.request(NSURLRequest(URL: NSURL(string: "http://httpbin.org/get")))
Applications can create managers for background and ephemeral sessions, as well as new managers that customize the default session configuration, such as for default headers (HTTPAdditionalHeaders
) or timeout interval (timeoutIntervalForRequest
).
let configuration = NSURLSessionConfiguration.defaultSessionConfiguration()
let manager = Alamofire.Manager(configuration: configuration)
let configuration = NSURLSessionConfiguration.backgroundSessionConfiguration("com.example.app.background")
let manager = Alamofire.Manager(configuration: configuration)
let configuration = NSURLSessionConfiguration.ephemeralSessionConfiguration()
let manager = Alamofire.Manager(configuration: configuration)
var defaultHeaders = Alamofire.Manager.sharedInstance.session.configuration.HTTPAdditionalHeaders ?? [:]
defaultHeaders["DNT"] = "1 (Do Not Track Enabled)"
let configuration = NSURLSessionConfiguration.defaultSessionConfiguration()
configuration.HTTPAdditionalHeaders = defaultHeaders
let manager = Alamofire.Manager(configuration: configuration)
This is not recommended for
Authorization
orContent-Type
headers. Instead, useURLRequestConvertible
andParameterEncoding
, respectively.
The result of a request
, upload
, or download
method is an instance of Alamofire.Request
. A request is always created using a constructor method from an owning manager, and never initialized directly.
Methods like authenticate
, validate
, and response
return the caller in order to facilitate chaining.
Requests can be suspended, resumed, and cancelled:
suspend()
: Suspends the underlying task and dispatch queueresume()
: Resumes the underlying task and dispatch queue. If the owning manager does not havestartRequestsImmediately
set totrue
, the request must callresume()
in order to start.cancel()
: Cancels the underlying task, producing an error that is passed to any registered response handlers.
Alamofire provides built-in response serialization for strings, JSON, and property lists, but others can be added in extensions on Alamofire.Request
.
For example, here's how a response handler using Ono might be implemented:
extension Request {
class func XMLResponseSerializer() -> Serializer {
return { (request, response, data) in
if data == nil {
return (nil, nil)
}
var XMLSerializationError: NSError?
let XML = ONOXMLDocument(data: data, &XMLSerializationError)
return (XML, XMLSerializationError)
}
}
func responseXMLDocument(completionHandler: (NSURLRequest, NSHTTPURLResponse?, ONOXMLDocument?, NSError?) -> Void) -> Self {
return response(serializer: Request.XMLResponseSerializer(), completionHandler: { (request, response, XML, error) in
completionHandler(request, response, XML as? ONOXMLDocument, error)
})
}
}
Generics can be used to provide automatic, type-safe response object serialization.
@objc public protocol ResponseObjectSerializable {
init?(response: NSHTTPURLResponse, representation: AnyObject)
}
extension Alamofire.Request {
public func responseObject<T: ResponseObjectSerializable>(completionHandler: (NSURLRequest, NSHTTPURLResponse?, T?, NSError?) -> Void) -> Self {
let serializer: Serializer = { (request, response, data) in
let JSONSerializer = Request.JSONResponseSerializer(options: .AllowFragments)
let (JSON: AnyObject?, serializationError) = JSONSerializer(request, response, data)
if response != nil && JSON != nil {
return (T(response: response!, representation: JSON!), nil)
} else {
return (nil, serializationError)
}
}
return response(serializer: serializer, completionHandler: { (request, response, object, error) in
completionHandler(request, response, object as? T, error)
})
}
}
final class User: ResponseObjectSerializable {
let username: String
let name: String
required init?(response: NSHTTPURLResponse, representation: AnyObject) {
self.username = response.URL!.lastPathComponent
self.name = representation.valueForKeyPath("name") as String
}
}
Alamofire.request(.GET, "http://example.com/users/mattt")
.responseObject { (_, _, user: User?, _) in
println(user)
}
The same approach can also be used to handle endpoints that return a representation of a collection of objects:
@objc public protocol ResponseCollectionSerializable {
class func collection(#response: NSHTTPURLResponse, representation: AnyObject) -> [Self]
}
extension Alamofire.Request {
public func responseCollection<T: ResponseCollectionSerializable>(completionHandler: (NSURLRequest, NSHTTPURLResponse?, [T]?, NSError?) -> Void) -> Self {
let serializer: Serializer = { (request, response, data) in
let JSONSerializer = Request.JSONResponseSerializer(options: .AllowFragments)
let (JSON: AnyObject?, serializationError) = JSONSerializer(request, response, data)
if response != nil && JSON != nil {
return (T.collection(response: response!, representation: JSON!), nil)
} else {
return (nil, serializationError)
}
}
return response(serializer: serializer, completionHandler: { (request, response, object, error) in
completionHandler(request, response, object as? [T], error)
})
}
}
Types adopting the URLStringConvertible
protocol can be used to construct URL strings, which are then used to construct URL requests. NSString
, NSURL
, NSURLComponents
, and NSURLRequest
conform to URLStringConvertible
by default, allowing any of them to be passed as URLString
parameters to the request
, upload
, and download
methods:
let string = NSString(string: "http://httpbin.org/post")
Alamofire.request(.POST, string)
let URL = NSURL(string: string)!
Alamofire.request(.POST, URL)
let URLRequest = NSURLRequest(URL: URL)
Alamofire.request(.POST, URLRequest) // overrides `HTTPMethod` of `URLRequest`
let URLComponents = NSURLComponents(URL: URL, resolvingAgainstBaseURL: true)
Alamofire.request(.POST, URLComponents)
Applications interacting with web applications in a significant manner are encouraged to have custom types conform to URLStringConvertible
as a convenient way to map domain-specific models to server resources.
extension User: URLStringConvertible {
static let baseURLString = "http://example.com"
var URLString: String {
return User.baseURLString + "/users/\(username)/"
}
}
let user = User(username: "mattt")
Alamofire.request(.GET, user) // http://example.com/users/mattt
Types adopting the URLRequestConvertible
protocol can be used to construct URL requests. NSURLRequest
conforms to URLRequestConvertible
by default, allowing it to be passed into request
, upload
, and download
methods directly (this is the recommended way to specify custom HTTP header fields or HTTP body for individual requests):
let URL = NSURL(string: "http://httpbin.org/post")!
let mutableURLRequest = NSMutableURLRequest(URL: URL)
mutableURLRequest.HTTPMethod = "POST"
let parameters = ["foo": "bar"]
var JSONSerializationError: NSError? = nil
mutableURLRequest.HTTPBody = NSJSONSerialization.dataWithJSONObject(parameters, options: nil, error: &JSONSerializationError)
mutableURLRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
Alamofire.request(mutableURLRequest)
Applications interacting with web applications in a significant manner are encouraged to have custom types conform to URLRequestConvertible
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.
enum Router: URLRequestConvertible {
static let baseURLString = "http://example.com"
static let perPage = 50
case Search(query: String, page: Int)
// MARK: URLRequestConvertible
var URLRequest: NSURLRequest {
let (path: String, parameters: [String: AnyObject]?) = {
switch self {
case .Search(let query, let page) where page > 1:
return ("/search", ["q": query, "offset": Router.perPage * page])
case .Search(let query, _):
return ("/search", ["q": query])
}
}()
let URL = NSURL(string: Router.baseURLString)!
let URLRequest = NSURLRequest(URL: URL.URLByAppendingPathComponent(path))
let encoding = Alamofire.ParameterEncoding.URL
return encoding.encode(URLRequest, parameters: parameters).0
}
}
Alamofire.request(Router.Search(query: "foo bar", page: 1)) // ?q=foo+bar&offset=50
enum Router: URLRequestConvertible {
static let baseURLString = "http://example.com"
static var OAuthToken: String?
case CreateUser([String: AnyObject])
case ReadUser(String)
case UpdateUser(String, [String: AnyObject])
case DestroyUser(String)
var method: Alamofire.Method {
switch self {
case .CreateUser:
return .POST
case .ReadUser:
return .GET
case .UpdateUser:
return .PUT
case .DestroyUser:
return .DELETE
}
}
var path: String {
switch self {
case .CreateUser:
return "/users"
case .ReadUser(let username):
return "/users/\(username)"
case .UpdateUser(let username, _):
return "/users/\(username)"
case .DestroyUser(let username):
return "/users/\(username)"
}
}
// MARK: URLRequestConvertible
var URLRequest: NSURLRequest {
let URL = NSURL(string: Router.baseURLString)!
let mutableURLRequest = NSMutableURLRequest(URL: URL.URLByAppendingPathComponent(path))
mutableURLRequest.HTTPMethod = method.rawValue
if let token = Router.OAuthToken {
mutableURLRequest.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
}
switch self {
case .CreateUser(let parameters):
return Alamofire.ParameterEncoding.JSON.encode(mutableURLRequest, parameters: parameters).0
case .UpdateUser(_, let parameters):
return Alamofire.ParameterEncoding.URL.encode(mutableURLRequest, parameters: parameters).0
default:
return mutableURLRequest
}
}
}
Alamofire.request(Router.ReadUser("mattt")) // GET /users/mattt
If you're 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.
It's important to note that two libraries aren't mutually exclusive: AFNetworking and Alamofire can peacefully exist in the same code base.
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't going anywhere.
Use AFNetworking for any of the following:
- UIKit extensions, such as asynchronously loading images to
UIImageView
- TLS verification, using
AFSecurityManager
- Situations requiring
NSOperation
orNSURLConnection
, usingAFURLConnectionOperation
- Network reachability monitoring, using
AFNetworkReachabilityManager
- Multipart HTTP request construction, using
AFHTTPRequestSerializer
Alamofire is named after the Alamo Fire flower, a hybrid variant of the Bluebonnet, the official state flower of Texas.
Alamofire is owned and maintained by the Alamofire Software Foundation.
Alamofire is released under the MIT license. See LICENSE for details.