基于接口的设计和可选的方法参数

Question

I am creating a C# wrapper library for a new Web API.

The service provides a set of a few APIs, where each method receives several mandatory parameters, and a few optional ones (each method may receive different mandatory/optional parameters).

The parameters are sent in a POST method, as a long string of param=value&param2=value2&....

Having gotten used to interface based design -- is it a good fit in this case?

I fail to find a good solution for mapping out ALL of the APIs methods and parameters into a single interface, without creating a of method overloads, creating a big mess, which would make it harder for the user to use.

Example of what it may look like:

public interface IServiceAPI
{
    void MethodA(string mandatory, string mandatory2);
    void MethodA(string mandatory, string mandatory2, int optional);
    void MethodB(string mandatory);

    ... etc
}

• I am aware of optional parameters that were introduced in .NET 4. This is not a good solution as this library is targeted for lower versions of .NET, and also because "optional parameters" are really just a way to set default values, and not for NOT SENDING any value for the parameter.

Is Interface based design may be a good fit here? or to put it differently - where does interface based design best fits?

Answer 1

First, I don't think designing an interface with a lot of overloads is a good idea. Unless the functions do something different you should just leave it up to whoever uses the interface if they want to put in some default values.

That said, secondly the entity that you're writing seems like it would serve you better as a base class. The name ServiceAPI lends itself to imply at least some amount of standard functionality. And this way you could have the multiple overloads and just let any child classes override the primary method.

Answer 2

Interfaces are the right way to go but I think you're using the wrong one. I would create an IOptionalParameter interface as follows:

interface IOptionalParameter<T>
{
    public bool IsSet {get;}
    public T Value {get;}
}

Then you can have just one method exposed in your API with each argument being of type IOptionalParameter.

This will also make the code you use for constructing the url request string neater. If it makes sense, you can add a Name property to the interface too thus simplifying it even further.

Update

To summarise the three different approaches and the trade-off between them:

1. Overloads - it is clearer that parameters are optional but leads to confusion as to potential differences in implementation and makes the implementation a bit messier
2. Nullable types - not very clear that the parameters are optional but cleaner on the implementation side
3. IOptionalParameter - explicitly states that parameters are optional or not and implementation is clean but horrible to call from the client side

Answer 3

It seems that your methods tend to have multiple parameters. To my experience, 3 arguments should be maximum. To solve this issue (and as a side-effect find a solution for optional/required parameters) I'd suggest packing parameters into a class:

class MethodAParameters
{
    public string Required1 {get;set;} //add validation in setter (nulls are not allowed)
    public string Required2 {get;set;} //add validation in setter (nulls are not allowed)
    public int? Optional1 {get;set;} //nulls allowed

    public MethodAParameters(string required1, string required2)
    {
        Required1 = required1;
        Required2 = required2;
    }
}

As you can see, such a design enforces passing required parameters (you cannot create an argument instance without specifying them) and allows adding optional parameters. Of course if some methods share the same subset of arguments then you ought to inherit parameter classes.

If null values are also relevant, then previously mentioned IOptionalParameter seems to be necessary (combined with this parameter class approach).

Please bear in mind that your code should be SOLID . When I look at the examples you provided I'm concerned about Single Responsibility Principle. Of course without knowing the actual code I'm only guessing, so treat it as a piece of advice.

Answer 4

Nullable data types?

For example instead of

void MethodA(string mandatory, string mandatory2);
void MethodA(string mandatory, string mandatory2, int optional);

You could simplify this to

void MethodA(string mandatory, string mandatory2, int? optional);

However, if the optional parameter was a reference type then it may not be as obvious to the caller that they could just pass null to it.

If you have a lot of optional parameters, like v oid MethodC(string mandatory, string mandatory2, string optional1, int? optional1, string optional2); you don't want to provide signatures for all the possible combinations, you could provide simply:

MethodC(string mandatory, string mandatory2) // for people that just want the basic functionality
MethodC(string mandatory, string mandatory2, string optional1, int? optional1, string optional2); // for people that want to specify extra, and they can pass null for some of the optional ones if they like.

Answer 5

I'm not sure why you want the as an interface as opposed to a regular class. Will other classes implement this interface, or are you just looking for a standard way to access the API?

If you're just looking for a standard way to access the API, I'd suggest a variation on the builder pattern. The builder pattern is normally used for classes, but I don't see why it can't be used for methods as well. See http://cdmckay.org/blog/2009/07/03/joshua-blochs-builder-pattern-in-csharp/ for a couple class-based examples.

Here's my attempt given what you supplied. I apologize if there are syntax errors, my editor at home is somewhat lacking...

public class AccessServiceAPI
{
    private void MethodA(string mandatory, string mandatory2, string optional)
    {
        // do stuff
    }

    public class MethodABuilder
    {
        private string Mandatory { get; set; }
        private string Mandatory2 { get; set; }
        private string Optional { get; set; }

        public MethodABuilder( string mandatory, string mandatory2)
        {
            Mandatory = mandatory;
            Mandatory2 = mandatory;
            Optional = "default value";
        }

        public MethodABuilder Optional( string optional )
        {
            Optional = optional;
            return this;
        }

        public void Build()
        {
            MethodA(mandatory, mandatory2, optional);
        }
    }
}

The client would then call the method like this:

MethodABuilder.Builder(mandatory, mandatory2).Optional(optional).Build();

If they don't want to set a value for an optional parameter, they can just skip it.