Nested resource class methods

[ob-stripe]

r? @brandur-stripe
cc @stripe/api-libraries

This PR is an attempt at fixing #420. It adds a nested_resource_class_methods DSL method that StripeObjects can use to define methods to access a nested resource without needing to retrieve the owning resource first.

E.g. you can now create a card on a customer like this:

card = Stripe::Customer.create_card(
  "cus_...",
  token: "tok_visa"
)

and update it like this:

updated_card = Stripe::Customer.update_card(
  "cus_...",
  "card_...",
  exp_month: 12,
  exp_year: 2020
)

This is helpful for users looking to minimize the number of outgoing API requests.

[brandur-stripe]

Wow, this is crazy awesome!

Looks good to me. Maybe the one doubt I have is that we will create two separate competing APIs for subresources. This adds:

account.create_login_link

When we already have:

account.login_links.create

It's not the end of the world, but it's sort of nice to have one "true" way of doing things — maybe we want to deprecate the old style in favor of the new (or something). Thoughts?

[ob-stripe]

Unless I'm mistaken, account.login_links.create would only work if you retrieved the account first. The create method is called on the ListObject that's returned by the API as the account's login_links attribute.

On the other hand, you can call Stripe::Account.create_login_link(account_id) without needing to retrieve the account first.

I do think we should keep the first way (retrieving the top-level resource first) as the "official" way in our docs. These new class methods are specifically for users looking to bypass the retrieval request.

[brandur-stripe]

Unless I'm mistaken, account.login_links.create would only work if you retrieved the account first. The create method is called on the ListObject that's returned by the API as the account's login_links attribute.

Oh right. I realize this is usable in cases where account.login_links.create isn't, but I guess what I was saying is that it introduces a new path in the case that account.login_links.create is available (as in a user can now alternatively call .create_login_link).

That said, this definitely solves a real problem, and the code looks great. Taking it in. Thanks!