How to handle many arguments in an API wrapper?

Question

I'm writing a PHP API wrapper for a third party API. I want to make all the methods consistent, but I'm not sure how to handle the number of arguments some API routes accept. One API request accepts up to 30 arguments. Obviously, it would be unwieldy to list each argument as a parameter on the method. Currently, I'm writing it to accept the required arguments as method paramaters, while all the optional ones are accepted in a final "additionalOptions" array.

public function sampleApiMethod($reqVal1, $reqVal2, $additionalOptions) {
    //Method Code
}

Unfortunately, there are API requests that have only optional arguments. In this case, either the only parameter is the array of options, or the method has individual parameters for optional arguments. When only passing an array, the method is consistent with the other methods, but it's not the most intuitive. With the latter option, I lose the consistent structure. Is there any sort of best practice or structure for an API wrapper that I should follow to try to have a consistent developer usage experience?

Answer 1

There are a couple good ways to handle this and it really comes down to your personal preference and just how complex your API interface really is. For a simple complexity interface I would increase the number of functions to be just the most specific calls to a given set of use cases. You might be lucky and find that if there are only 10 different use case actions where an actor might need different combinations of required and optional arguments then one might just create ten different functions for this.

This may not be the best solution however if there are a large combination of arguments and use cases to consider.

Check out the Builder Pattern

The premise of the Builder pattern is that your object class will contain a special builder class object that can construct your object through function calls that return the same object. This allows for fluid code that is much more verbose and clear to a client of the API. This can be much more useful in representing a function's parameters than an extremely long list of arguments and prevents the common problem of a client accidentally mismatching arguments. The client is forced to be verbose in building his arguments.

sendPizza ( pizzaBuilder->buildPeppers()->buildSausage()->etc...)

One is able to instantly look at the client code and decipher the breadth of arguments passed to sendPizza.

Answer 2

I like that you separate out the required options from the optional ones. If you don't use a Builder, then for optional parameters, even when there are no required parameters, I'd definitely use an associative array or "map". I think you are calling this just an "array" because PHP calls it that, but I'm not sure.

Builder Pattern lets you build the most airtight API, as @maple_shaft said. It prevents clients from entering invalid keys into the parameter array and its functional nature lets you fail fast as soon as an invalid value is passed. I would agree that that would be the best answer in most cases.

But the Builder pattern can require a fair amount of up-front programming work to make your API easy to use for your clients. It may not be as PHP-ish as your associative arrays - I wouldn't know. For completeness I feel I should mention some other options. The first one may be what you are doing already...

Named Parameter Map

class MyApi {
    const Param1Name = 0;
    const Param2Name = 1;
    // etc.

    public function sampleApiMethod($myParamHash) {
        //Method Code
        $localParam1 = $myParamHash[Param1Name]
    }
}

// Load up params using pre-defined symbolic names to prevent typos
$myParamHash = array (MyApi::Param1Name => 5,
                      MyApi::Param2Name => 9);

// call method
sampleApiMethod($myParamHash);

The beauty of this option (or the builder) is that it makes it clear which parameter is which, thus avoiding a lot of potential errors.

Default Values

I just did a quick search, and it seems that PHP supports default values for arguments. These are probably better than Telescoping Methods, but there may be some cases where telescoping works and default values don't so I'll mention...

Telescoping Methods

Not sure if this works in php, but Something like:

public function sampleApiMethod($reqVal1, $reqVal2, $additionalOptions) {
    //Method Code
}
public function sampleApiMethod($reqVal1, $reqVal2) {
    sampleApiMethod($reqVal1, $reqVal2, null);
}
public function sampleApiMethod($reqVal1) {
    sampleApiMethod($reqVal1, null, null);
}

I'm using "null" for default values. But for an API, this makes things much easier on the caller without the work of creating a builder. Just put the most commonly used arguments first and provide sensible defaults in your telescoping methods.

Re-Examine Your Model

Almost all useful programs model some real-world things or actions. An API that takes 30 parameters strikes me as a red flag that there may be some higher-level design issues in your API. You might want to provide a model for some of the things you are passing in as primitive values. Functional people would model things in terms of functions, OO people in terms of objects. Take your pick.