Ruby Lib API Versioning

[Ryan]

Two questions:

1.  How do you version the API with the Ruby Library dynamically?

We are using connect and passing API Keys like Stripe::Customer.retrieve('cus_1234567890', { api_key: 'sk_asdfasdfasdf' }) where the api_key is our connected account key.  I tried to pass api_version: '2017-05-25' there as well, but it didn't seem to work...which leads to my next question.

2.  Is there a way to validate the API Version in the response?  Like if we make a call to know it is the API version we are specifying or whatever is set if we aren't overriding?

Thanks!

[Remi J.]

Hey Ryan,

By default, we use the API version set on the Stripe account associated with the API key you use when making the request. You can then override this API version globally when you load our library in Ruby by setting `Stripe.api_version` [1]. This would apply to all API requests made with the library while it's loaded.

Sometimes though you want to set a specific API version for one request without impacting the rest of your code. This is common when you're working on upgrading your integration based on the recent API changes [2] but want to do this one API request at time. In that case, you need to pass the `stripe_version` in the second hash along with your API key (assuming it's not set globally).

To confirm that it works, you can choose a specific API change and then check the response based on what we return. For example, the API version 2015-10-12 [3] shipped a major change that returned an error if you passed invalid parameters in the `card` hash when creating a card token. This means that if you use a recent API version you get an error with the extra parameter but if you force an earlier API version such as 2015-10-01 [4] then no error would be returned.

You can test the following code using Stripe's default Test Secret key and see that forcing the API version lets the token be created: https://gist.github.com/anonymous/5154a2da16b54e88a70b0059aa6f99c3

When using Stripe Connect, the logic is the same. The API key you use here is not the account's API key. It's an access token which represents an API key specific to both your platform and this account. The API version used in that case is always the platform's API version. This means that no matter which API version a connected account is on, your integration will always work as expected as it will be based on your own API version.

For the second question, It is not possible to know which API version you're currently using by looking simply at the response from the API. It's not something we surface. Usually, your account is pinned to an API version and you only upgrade when you need a new feature. I often recommend that you explicitly set an API version in your code though, either globally on per request. This ensure that if you upgrade by mistake in the dashboard, it doesn't impact your Live integration and lets you upgrade in smaller chunks too.

One thing to note is that Events generated on your account and sent to your webhook endpoint are always generated based on the API version on the account. The API version you force via the API won't affect the payload of the event and it will always follow the account's API version at the time of its generation.

Hope this helps!

Remi

[1] https://stripe.com/docs/api/ruby#versioning

[2] https://stripe.com/docs/upgrades

[3] https://stripe.com/docs/upgrades#2015-10-12

[4] https://stripe.com/docs/upgrades#2015-10-01

--
You received this message because you are subscribed to the Google Groups "Stripe API Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss+unsubscribe@lists.stripe.com.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at https://groups.google.com/a/lists.stripe.com/group/api-discuss/.

[Brandur Leach]

> For the second question, It is not possible to know which

> API version you're currently using by looking simply at

> the response from the API. It's not something we surface.

> Usually, your account is pinned to an API version and you

> only upgrade when you need a new feature. I often

> recommend that you explicitly set an API version in your

> code though, either globally on per request. This ensure

> that if you upgrade by mistake in the dashboard, it

> doesn't impact your Live integration and lets you upgrade

> in smaller chunks too.

I was just chatting a bit with Remi off list, and while

this is quite new, stripe-ruby 2.0+ does provide with a way

of accessing response headers, which will allow you to

verify the API version that you received:

    require "stripe"

    Stripe.api_key = "sk_test_..."

    _event, response = client.request do

      Stripe::Charge.retrieve("ch_1ANtLm2eZvKYlo2CaEwdolc2", stripe_version: "2017-05-25")

    end

    # prints "2017-05-25"

    p response.http_headers["Stripe-Version"]

I'm glad Remi got to this response first though, because it

has a lot more depth than what I would've written!

[Ryan]

Helpful info!  It'd be awesome to access the headers.

Got it!  So it's `stripe_version` not `api_version` in the ruby lib.

Thanks!