Proper usage of the Alamofire's URLRequestConvertible

Great questions. Let's break down each one individually.

What is the proper usage of URLRequestConvertible in real world API?

The URLRequestConvertible protocol is a lightweight way to ensure a given object can create a valid NSURLRequest. There's not really a strict set of rules or guidelines that exist forcing you to use this protocol in any particular way. It's merely a convenience protocol to allow other objects to store state required to properly create the NSURLRequest. Some more information relating to Alamofire can be found here.

Should I create one Router per endpoint?

Definitely not. That would defeat the entire purpose of using an Enum. Swift Enum objects are amazingly powerful allowing you to share a large amount of common state, and switch on the parts that actually different. Being able to create an NSURLRequest with something as simple as the following is really powerful!

let URLRequest: NSURLRequest = Router.ReadUser("cnoon")

I can't figure out why enum is used for building router? Why we don't use class with static methods?

An enum is being used because it is a much more concise way of expressing multiple related objects under a common interface. All the methods are shared between all the cases. If you used static methods, you'd have to have a static method for each case for each method. Or you would have to use an Obj-C styled enum inside the object. Here's a quick example of what I mean.

enum Router: URLRequestConvertible {    static let baseURLString = "http://example.com"    case CreateUser([String: AnyObject])    case ReadUser(String)    case UpdateUser(String, [String: AnyObject])    case DestroyUser(String)    var method: Alamofire.HTTPMethod {        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)"        }    }}

To get the method of any of the different endpoints, you can call the same method without having to pass in any parameters to define what type of endpoint you are looking for, it's already handled by the case you select.

let createUserMethod = Router.CreateUser.methodlet updateUserMethod = Router.UpdateUser.method

Or if you want to get the path, same types of calls.

let updateUserPath = Router.UpdateUser.pathlet destroyUserPath = Router.DestroyUser.path

Now let's try the same approach using static methods.

struct Router: URLRequestConvertible {    static let baseURLString = "http://example.com"    static var method: Method {        // how do I pick which endpoint?    }    static func methodForEndpoint(endpoint: String) -> Method {        // but then I have to pass in the endpoint each time        // what if I use the wrong key?        // possible solution...use an Obj-C style enum without functions?        // best solution, merge both concepts and bingo, Swift enums emerge    }    static var path: String {        // bummer...I have the same problem in this method too.    }    static func pathForEndpoint(endpoint: String) -> String {        // I guess I could pass the endpoint key again?    }    static var pathForCreateUser: String {        // I've got it, let's just create individual properties for each type        return "/create/user/path"    }    static var pathForUpdateUser: String {        // this is going to get really repetitive for each case for each method        return "/update/user/path"    }    // This approach gets sloppy pretty quickly}

NOTE: If you don't have many properties or functions that switch on the cases, then an enum doesn't present many advantages over a struct. It is simply an alternative approach with different syntactic sugar.

Enums can maximize state and code reuse. The associated values also allow you to do some really powerful things like grouping objects that are somewhat similar, but have incredibly different requirements...such as NSURLRequest creation.

What is the right way to construct parameters for enum cases to improve readability? (had to mash this one together)

That's a terrific question. You've already laid out two possible options. Let me add a third that may suit your needs a bit better.

case CreateUser(username: String, firstName: String, lastName: String, email: String)case ReadUser(username: String)case UpdateUser(username: String, firstName: String, lastName: String, email: String)case DestroyUser(username: String)

In cases where you have associated values, I think it can be helpful to add explicit names for all the values in the tuple. This really helps build the context. The downside is that you then have to redeclare those values in your switch statements like so.

static var method: String {    switch self {    case let CreateUser(username: username, firstName: firstName, lastName: lastName, email: email):        return "POST"    default:        return "GET"    }}

While this gives you a nice, consistent context, it gets pretty verbose. Those are your three options at the moment in Swift, which one is the correct one to use depends on your use case.

Update

With the release of 🔥🔥 Alamofire 4.0 🔥🔥, the URLRequestConvertible can now be MUCH smarter and can also throw. We've added full support into Alamofire for handling invalid requests and generating sensible errors through the response handlers. This new system is documented in detail in our README.

Here is the up to date enum Router in Swift 3, which is recommend on Alamofire's Github. I hope you find it useful in terms of how to properly implement a Router with URLRequestConvertible.

import Alamofireenum Router: URLRequestConvertible{    case createUser(parameters: Parameters)    case readUser(username: String)    case updateUser(username: String, parameters: Parameters)    case destroyUser(username: String)    static let baseURLString = "https://example.com"    var method: HTTPMethod    {        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    func asURLRequest() throws -> URLRequest    {        let url = try Router.baseURLString.asURL()        var urlRequest = URLRequest(url: url.appendingPathComponent(path))        urlRequest.httpMethod = method.rawValue        switch self {        case .createUser(let parameters):            urlRequest = try URLEncoding.default.encode(urlRequest, with: parameters)        case .updateUser(_, let parameters):            urlRequest = try URLEncoding.default.encode(urlRequest, with: parameters)        default:            break        }        return urlRequest    }}

Why don't you try to use SweetRouter. It will help you to remove all the boilerplate that you have when declaring a Router and it also supports such things as multiple environments and your code will be really readible.

Here's an example of the Router with sweet router:

struct Api: EndpointType {    enum Environment: EnvironmentType {        case localhost        case test        case production        var value: URL.Environment {            switch self {            case .localhost: return .localhost(8080)            case .test: return .init(IP(126, 251, 20, 32))            case .production: return .init(.https, "myproductionserver.com", 3000)            }        }    }    enum Route: RouteType {        case auth, me        case posts(for: Date)        var route: URL.Route {            switch self {            case .me: return .init(at: "me")            case .auth: return .init(at: "auth")            case let .posts(for: date):                return URL.Route(at: "posts").query(("date", date), ("userId", "someId"))            }        }    }    static let current: Environment = .localhost}

And here's how you would use it:

Alamofire.request(Router<Api>(at: .me))Alamofire.request(Router<Api>(.test, at: .auth))Alamofire.request(Router<Api>(.production, at: .posts(for: Date())))