search

stripe / stripe-mock

stripe-mock is a mock HTTP server that responds like the real Stripe API. It can be used instead of Stripe's testmode to make test suites integrating with Stripe faster and less brittle.
MIT License
1.38k stars 110 forks source link

Account create (capabilities vs requested_capabilities) #235

Closed mastacheata closed 4 years ago

mastacheata commented 4 years ago

The Stripe API documentation describes a capabilities key that is supposed to contain a dictionary of capabilities which themselves are dictionaries with one boolean property called requested that is set to true if you want to request a capability. The SDK examples all show a requested_capabilities list of strings instead.

The same is true for the openAPI spec3 vs spec3.sdk files.

Apparently the actual API still accepts both ways of requesting capabilities when creating accounts, but the mock server only accepts the capabilities dictionary and not the requested_capabilities list anymore as of some time last week. (couldn't find the exact commit and the API changelog doesn't mention this either)

Is this an oversight and the two API specs will be updated to the same state soon or is this an error in the Stripe Mock to only use one of two possible API specs?

remi-stripe commented 4 years ago

@mastacheata passing requested_capabilities: ['capab1', 'capab2'] is considered deprecated. This was the original shape and it's not something we recommend anymore. The new approach is passing capabilities: {capab1: {requested: true}, capab2: {requested: false}}.

When we deprecate features like this, the first step is to undocument them so that no new developers rely on them. While we do that, we keep supporting the old way though to ensure we don't break any existing integrations. In the future, we will also release an API version that removes support for requested_capabilities (though it will keep working on older API versions).

When features get undocumented they also get removed from our openapi spec and from stripe-mock which is why stripe-mock doesn't support this. We aim for stripe-mock to represent the latest version of our API.

I hope this clears things up!

mastacheata commented 4 years ago

My problem is actually this is still the way in which it's documented. If you check the API reference ALL example code from curl to python still uses requested capabilities.

Same for the openapi spec SDK files (I guess this is how you generate the right hand Side of the API reference).

I was completely unaware of this being deprecated. It's not listed on the API changelog and the API reference example code is all using the deprecated way.🤷‍♂️

remi-stripe commented 4 years ago

@mastacheata The API reference is definitely not correct and I'll get this fixed, sorry about that one.

We don't document changes like this directly since everything still just works. It would be documented in the future when we actively remove support for requested_capabilities in an API version. But when we make those changes we do our best to minimize the impact on existing integrations and aim to get newer integrations to use the better way (when we fix the docs that is).