API version in the dashboard

[Herb Jellinek]

I know I can control my Java code's interactions with Stripe by selecting the appropriate Stripe jar file and by specifying a Stripe API version when I use objects and methods in that jar.

But I just noticed a third thing that might also affect my programs' behavior, and I'm not sure how/if it relates.  It's the Stripe API version control in the dashboard: Account Settings > API Keys > API version: Upgrade... (see image attached).

I don't recall a discussion of this on this list, and I apologize if this is old stuff.  I'm guessing that it simply governs the version of the API that my dashboard itself is using, but I figured I'd ask.

- What happens if I push that "Upgrade..." button?
- Having done so, what effect (if any) will I see in my programs' use of the Stripe API?
- Can I later "Downgrade...."?

Thanks.

[Jim Danz]

Hi Herb,

API requests made using the dashboard itself always use the latest API
version. Said another way, regardless of your API version in your
settings or the one that you send in the headers of your own API
requests, the dashboard itself always uses the latest&greatest.

Once you're specifying the API version in your requests, the only
thing that using the "Upgrade" button in the dashboard will change is
the API version that is used to render your webhooks. To be specific,
if you made a charge creation request with the Stripe-Version header
set to Foo, but your account's API version is Bar in the dashboard,
the charge.created event that gets sent to any webhook endpoints that
you have will be rendered using version Bar.

You cannot later downgrade.

Hope this helps,
Jim

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

[Bill Huneke]

The biggest problem with Stripe's webhook design is the fact that you cannot select specifically the version you want to receive. As a result of this, anyone using "plugins" (e.g. django-stripe-payments) has no way to ensure that Stripe will send webhook data that that plugin can understand.

- Should I upgrade my fork of the plugin to match my version of the webhook data? Not so ideal. That's a pretty deep change, hard to merge future updates from upstream

- Should I just run that plugin with whatever API version I happen to be stuck with in my particular Stripe account?  I guess I have to. With this, I just have to pray that the objects you send my plugin's webhook endpoint will be properly processed

These are both terrible options.

Here's how I think Stripe ought to do it: for every webhook endpoint in a person's account, allow them to indicate exactly which version they want to use

This is because an endpoint will always map to particular plugin or hook-processing code base. That code base will always have a particular api version that it has been tested against.

What do you think? What do you suggest? How can I use the webhook feature if I can't receive hook data in the format that my endpoint recognizes/was coded for?

And as for forcing people to upgrade, not downgrade. I can understand your desire to gradually forcibly move everyone towards new code, but for the reasons explained above it really causes big problems for anyone using a Stripe "plugin". Better policy would be scheduled and gradual sunsetting of old api versions.  But until a version is sunsetted, you should not prevent people using it!

[Oscar Rovira]

+1

Also, to be able to set different API versions in test and live mode would be useful while you're upgrading your code base.

Oscar

--

[Matthew Arkin]

Stripe does allow you to specify the API version when you make an API call using the Stripe-Version header [1]. It would make some sense for the plugin to re-retrieve the event from Stripe and specify the version it expects. Then it'll have a copy of the Event object in an format its expecting. 

It gets a little more complicated from here. The data object in the event object is a snapshot of the object the event targets at the time that it happened. So if its a charge.succeeded event, data is a snapshot of the charge object when the event happened. This snapshot ends up being in the api version of your account. This also means that if you request the event object with a specific version, event.object won't necessarily be the version you requested. You could get around this by then requesting the object of the event using the appropriate retrieve API but you're not guaranteed that the object would be in the same state (this is less a problem in the webhook use case than it may be if you need to retrieve old events).

Because of how the event object is structured, Stripe would also have to add the version translator to the object of the event when its retrieved (I don't know how difficult that would be, I'd defer to a Stripe), or keep different version of it based on your webhooks versions. 

If the plugin was to retrieve the event and the event's object with the Stripe-Version header it should all work though. 

--

[Bill Huneke]

Thanks very much, Matthew! This is great advice and, as work arounds go, not too bad. The aforementioned django stripe plugin currently does an event request but then asserts that the event retrieved by api should match exactly the event sent by webhook. This design does not match what you recommend and it will clearly not work in many/most cases.

I do have great respect for how Stripe has arranged their API. If they would just consider my idea of binding API version to webhook endpoint (instead of account) I think it would be even more amazing.

Can you recommend the best way to put this idea in front of a Stripe tech person?

Thanks again,

Bill

[Matthew Arkin]

Someone from Stripe should see this thread (I'll ping a contact to be sure it gets discussed internally though).

Matt

[Brian Krausz]

We're definitely listening :). There are some challenges to allowing you to select webhook versions. Specifically, we render the object descriptions at webhook generation time. So while you could change the version for a webhook, any events before that moment would still be in the old version. Our goal is to make it easy to upgrade webhooks, so we'd rather be slightly more opinionated.

To that effect, what I'd like to see is a 3-stage process:

1) Your endpoint gets old version A (current state)

2) You press a button, and your endpoint starts getting both version A & B (double webhooks)

3) Once you finish testing B, you press another button, and we stop sending you A

That way, rather than giving fine-grained control that may be confusing due to how we render webhooks, we help you through the upgrade process.

I unfortunately have no timeframe for this, or any other potential fix we've discussed, but it's definitely on our list and gets discussed every time we prioritize projects.

Thanks,

Brian

--

[Bill Huneke]

A point that I'm not sure echoed there: being able to choose the specific API version. I think this is really the most critical part. I hope this is not what you were referring to as "fine-grained" that would be too confusing.

Those of us who choose not to implement their own Stripe code (those of using "plugins" such dj-stripe for Django) effectively cannot choose exactly which version of the Stripe API we will support at any given time. Rather, we pick up the plugin and install it. The plugin tells us which stripe api version it expects and we need to be able to select that API version in our Stripe dashboard. Eventually, we upgrade that plugin and the upgraded version of the plugin tells us which API version it now supports. This dictates what our A and B will be in an upgrade of our webhook processing.

Thanks!

[Brian Krausz]

Excellent feedback: the third party software case hadn't occurred to me. I'll be sure to keep that in mind when we get to implementing a solution here.

Thanks,

Brian

[Bill Huneke]

Great! glad we talked it through