Add a README section for globally configuration an API version

[brandur]

I don't remember why I wrote this originally, but found it sitting
locally uncommitted. It seems like a useful example to have in the
README, so add it in.

r? @ob-stripe

[remi-stripe]

@brandur Should we link to https://stripe.com/docs/api#versioning instead?
It is likely more useful to explain how to do this on a per-request basis in https://github.com/stripe/stripe-ruby#per-request-configuration

[brandur-stripe]

@remi-stripe Ah, good question! I guess I kind of thing that just including it in the README isn't too bad — it's not likely to change, and it'll make a handy reference for someone. Would you be okay if I reworded it to also include a link to the reference docs?

And yeah, agree that we should add stripe_version to the per-request section. I'll change that.

[remi-stripe]

I agree it is useful as long as we link to the official doc too it's a great addition!

[brandur-stripe]

Thanks @remi-stripe! I've made the suggested changes — would you mind taking the review given that you seem to have already familiarized yourself with the PR? :)

[remi-stripe]

Minor comment on the per-request example but feel free to merge as is!

[remi-stripe]

shouldn't this be in its own hash? Like I know it works but we usually recommend having 2 separate hashes right? If so, we need to change the example below to be id + {} + {xxxx}a

[brandur-stripe]

Yeah, it's a little cleaner as two hashes. I've updated both examples.

I'm not sure I understood what you meant by id + {} + {xxxx} though — would you mind taking another look to make sure this is what you had in mind? The signature for retrieve should just be retrieve(id, opts = {}).

[remi-stripe]

so the issue is that the Charge Retrieve API (And any retrieve) supports expand. And that would be in the first hash. So really the call should be

Stripe::Charge.retrieve(
  "ch_18atAXCdGbJFKhCuBAa4532Z",
  {}, // where expand would go
  {
    :api_key => "sk_test_...",
    :stripe_account => "acct_...",
    :stripe_version => "2018-02-28"
  }
)

right?

[brandur-stripe]

Okay, it's really bad that this is confusing to even us, but the correct invocation with an expansion is this (include both the retrieval ID and expand in one hash):

Stripe::Charge.retrieve( { id: "ch_1COBry2eZvKYlo2CmgIUoaBZ", expand: [:customer] }, { stripe_version: "2018-02-28" })

The method won't take three parameters:

[28] pry(main)> Stripe::Charge.retrieve("ch_1COBry2eZvKYlo2CmgIUoaBZ", {}, {})
ArgumentError: wrong number of arguments (3 for 1..2)
from /Users/brandur/stripe/stripe-ruby/lib/stripe/api_resource.rb:61:in `retrieve'

[remi-stripe]

Ah damn it you're right I though it depended on the language but it does not.

[brandur-stripe]

Thanks Remi!