This PR is an alternative to #1464 that goes WAY further in refactoring the ParameterEncoding logic into a protocol instead of an enumeration.

Motivation

The ParameterEncoding enum hasn't been flexible enough to allow us to customize the behavior of a particular encoding type. For example, we had to introduce the new .urlEncodedInURL case just to allow users to be able to force the parameters into the query string when their backends required them to do so on a POST or PUT.

The enum also doesn't allow us to open up different writing options for the JSON and plist serializers. We can't customize plist formats, etc. The list goes on and on since we're locked to the enum that can't add extra cases or associated values in a backwards compatible manner.

Solution

Get rid of the enumeration altogether! Now the ParameterEncoding type of a protocol backed by concrete URL, JSON and PropertyList conforming structs.

public typealias Parameters = [String: Any]

public protocol ParameterEncoding {
    func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest
}

It was amazing after I split everything up how much sense it really makes. ParameterEncoding implementations are now free of the enumeration bounds and are free to customize to their own needs.

URLEncoding

The .url and .urlEncodedInURL cases have now been combined in the URLEncoding struct with some new enumerations and properties of it's own.

public struct URLEncoding: ParameterEncoding {
    public enum Destination {
        case methodDependent, queryString, httpBody
    }

    public static var `default`: URLEncoding { return URLEncoding() }
    public static var methodDependent: URLEncoding { return URLEncoding() }
    public static var queryString: URLEncoding { return URLEncoding(destination: .queryString) }
    public static var httpBody: URLEncoding { return URLEncoding(destination: .httpBody) }

    public let destination: Destination

    public init(destination: Destination = .methodDependent) {
        self.destination = destination
    }

    public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
        // left out for simplicity
    }
}

I added convenience properties for accessing instances without having to go through the initializer. This was a nice touch. We could actually hide the initializer if we wanted, but I figured that was a step too far.

JSONEncoding

The JSONEncoding struct is much less complicated than the URLEncoding struct for obvious reasons.

It's simpler!

public struct JSONEncoding: ParameterEncoding {
    public static var `default`: JSONEncoding { return JSONEncoding() }
    public static var prettyPrinted: JSONEncoding { return JSONEncoding(options: .prettyPrinted) }

    public let options: JSONSerialization.WritingOptions

    public init(options: JSONSerialization.WritingOptions = []) {
        self.options = options
    }

    public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
        // left out for simplicity
    }
}

PropertyListEncoding

The PropertyListEncoding struct is very similar to the JSONEncoding struct, just with a few more properties.

public struct PropertyListEncoding: ParameterEncoding {
    public static var `default`: PropertyListEncoding { return PropertyListEncoding() }
    public static var xml: PropertyListEncoding { return PropertyListEncoding(format: .xml) }
    public static var binary: PropertyListEncoding { return PropertyListEncoding(format: .binary) }

    public let format: PropertyListSerialization.PropertyListFormat
    public let options: PropertyListSerialization.WriteOptions

    public init(
        format: PropertyListSerialization.PropertyListFormat = .xml,
        options: PropertyListSerialization.WriteOptions = 0)
    {
        self.format = format
        self.options = options
    }

    public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
        // left out for simplicity
    }
}

If you noticed default and xml are exact duplicate properties, bonus points for you. I wanted to follow the same .default property convention across all the ParameterEncoding types for consistency. That way at the call sight you can always use <encoding_struct>.default and know it will be there. I wonder if that should be enforced in the protocol 🤔

Wrapping Up Parameters with Encoding

So I tried for probably 2 hours to work the parameters and the encoding into a single type. I had Parameters as the protocol and URLParameters, JSONParameters, etc. and you'd create the object like URLParameters(parameters) and call it like so:

Alamofire.request(urlString, parameters: URLParameters(parameters)

Part of this was great because it got rid of the encoding parameter altogether which I was all for. However, it greatly increased the majority of our calls because it can't rely on the default parameter value of .url anymore. So we end up having to write URLParameters(parameters) everywhere instead of just parameters. Not to mention it just feels a little off.

Because of all of this, I finally decided enough was enough and it was just a square peg, round hole scenario. Once I backed away, I was able to finally land on the solution you see here.

Throwing vs. Double Tuple

This also includes all the changes to the encode method itself which was part of the previous PR. These changes should definitely be adopted in AF 4. It's time to eliminate the last odd double optional case we have left! 🙌🏼🏆

Summary

Overall, I think this is an awesome set of changes for AF 4. It makes it so much easier to create your own custom ParameterEncoding type. It also rids the world of the .urlEncodedInURL case that I sadly had to introduce a year ago.