Mark deprecated features in the spec

[yusuf-musleh]

Hey There!

I have a few questions about the OpenAPI spec:

1. I noticed the Create Charge endpoint (POST /v1/charges) in the spec had an extra parameter defined in the request body called card that I could not find in the latest docs.

                  "card": {
                    "anyOf": [
                      {
                        "properties": {
                          "address_city": {
                            "maxLength": 5000,
                            "type": "string"
                          },
                         // ...
                        },
                        "required": [
                          "exp_month",
                          "exp_year",
                          "number"
                        ],
                        "title": "customer_payment_source_card",
                        "type": "object"
                      },
                      {
                        "maxLength": 5000,
                        "type": "string"
                      }
                    ],
                    "description": "A token, like the ones returned by [Stripe.js](https://stripe.com/docs/stripe.js).",
                    "x-stripeBypassValidation": true
                  },

I was wondering how in-sync the OpenAPI spec is with API docs and the actual released API in general. Is that a new field that will be added in a later version, or just a typo and shouldn't be there?

2. I also noticed that some parameters in the request body, mainly objects, are defined with anyOf and lists between the properties of the object or an empty enum, like the following from POST /v1/customers:

                  "address": {
                    "anyOf": [
                      {
                        "properties": {
                          "city": {
                            "maxLength": 5000,
                            "type": "string"
                          },
                          // ...
                        },
                        "required": [
                          "line1"
                        ],
                        "title": "address",
                        "type": "object"
                      },
                      {
                        "enum": [
                          ""
                        ],
                        "type": "string"
                      }
                    ],
                    "description": "The customer's address."
                  },

Does that imply that the address object is an optional parameter, as it's mentioned in the docs, and that's just hows its represented in the OpenAPI spec?

I'd appreciate it if someone can help shed some light on my questions.

Thanks!

[remi-stripe]

@yusuf-musleh Thanks for reaching out. The card parameter on Charge creation is a legacy parameter that was deprecated on 2015-02-18 when we introduced the source parameter instead. It's in the spec for legacy reasons though we hope to be able to remove it in the future. I'd recommend ignoring it/not using it.

As for the address it's because it's a hash that can be nulled out. To unset all properties in a hash in our API you pass an empty string so you can send address="" and that will remove the whole hash.

Does this help clarify the issues?

[yusuf-musleh]

Hi @remi-stripe , that makes sense, thanks for getting back to me and clarifying the issues.

Quick followup, since I am going through the spec programmatically, do you have any suggestions for me to be able to tell which fields or even some endpoints are present for legacy purposes but in reality are deprecated or should not used?

Here are a few things I noticed for example:

• Some endpoints explicitly mention (for some of their methods) that they are deprecated ("deprecated": true), like GET /v1/customers/{customer}/bank_accounts/{id} but not for the DELETE or POST methods for that endpoint. Does that mean that only the GET method has been deprecated?

• /v1/accounts vs /v1/account. It seems like /v1/accounts is the correct one to use, since that's the URL I see in the docs and in the internals of stripe-node sdk as well, but in the spec it doesn't mention that /v1/account was deprecated

• Similarly /bank_accounts seems to have been deprecated as well, as its not present in the docs, for all of /v1/accounts/, /v1/account/ or /v1/customers/ where it appears under, but is not explicitly mentioned in the spec that they were

It would be really helpful if there was a way for me to tell which endpoints/fields to ignore as I go through the spec.

[remi-stripe]

Unfortunately we don't really have a good way to represent deprecated features at the moment. It's something we want to improve in the future but it won't happen in the short term just yet.