Change how API versions are set

Pinning all stripe requests to a specific API version is a good idea and recommended, yet the way this is currently done using the SDK is a bit strange and, I would argue, even a bit dangerous.

const Stripe = require('stripe');
const stripe = new Stripe('my-secret-key');
stripe.setApiVersion('2019-02-19');

The setApiVersion() method is strange because it is setting an option that really belongs in either the constructor or each API method call. As far as I am aware, it is the only option that uses a method to set it. Currently, you cannot do new Stripe({ apiVersion : '2019-02-19' }), which makes it inconsistent with how the secret key is set. ~You also cannot do stripe.customers.retrieve(customerId, { apiVersion : '2019-02-19' }), which makes it inconsistent with how the stripe_account option is set.~ The fact that it’s done with a method also forces me to add an extra if statement to one of my modules, which is a small but annoying inconvenience.

Additionally, the setApiVersion() method is dangerous because it gives the impression that it is okay to set the API version at any time before calling a Stripe API. This is problematic because if a single instance of the SDK is used across multiple routes on a server (very common use case), then we are prone to one route accidentally influencing the API version used by other, separate routes. You have to be very careful to first read the existing API version, then set the new API version, then call the desired Stripe API, and finally set the API version back to what it was originally. Yet even then, you are prone to race conditions between routes.

I think moving this option to the constructor would be a great improvement to the SDK and that alone is probably sufficient. However, if people are relying on the ability to override the version for individual API calls, then this option should be supported on each API method.

[paulasjes-stripe]

We talked about this internally and we’ve split it into a few tasks:

1. Move setApiVersion to be set via a config object in the Stripe object initialization, with the intention of deprecating stripe.setApiVersion
2. Move other setters like setMaxNetworkRetires to be set via the config object
3. Change maxNetworkRetries so it can be set on a per-request basis as well as a global setting

The config object in task 1 will need to be quite strict about what it accepts, throwing errors if it contains something unexpected.

[paulasjes-stripe]

Fixed in https://github.com/stripe/stripe-node/pull/703