Should the payment API be more conversational or less conversational?

[msporny]

Partial migration from w3c/webpayments#55:

@dlongley proposed a more conversational shape to the browser payment API here:

http://sites.local/web-payments-browser-api/checkout-api.html#the-checkout-interface

For example:

var checkout = new Checkout();
checkout
  .send('paymentItem', paymentItems)  // send line item estimate to UA
  .request('shippingAddress')         // request shippingAddress from UA
  .start()                            // start the checkout UI
  .then(finishCheckout);              // checkout UI has collected the info

and @dlongley noted this is how it would work:

With the Checkout API, we want to be able to do things like make shipping options depend on the shipping address selected. What we're exploring essentially works like this:

1. A Checkout object is created by a webpage.
2. A call to send the line item estimate is made on the Checkout object. This call essentially just sets "options" that will be read once the checkout is started.
3. A call to request shipping address is made on the Checkout object. Again, this call is like setting options as it simply "indicates" that a shipping address is requested. It won't do anything until the checkout is started.
4. A call to start checkout is made on the Checkout object. This returns a Promise that will settle once the user clicks "Buy".
5. The browser UI opens and sees the line item estimate and displays it. It sees that shipping was requested, so it knows to show the user a shipping address selection UI. The "Buy" button will be disabled.
6. The user selects a shipping address and a shippingAddressChanged event is dispatched.
7. An event handler may optionally call request to request shipping option selection along with a list of possible shipping options (or a Promise that resolves to such a list).
8. Once event dispatching has completed, if request was called, it will wait for its Promise to settle and then display the shipping options in the UI, keeping the "Buy" button disabled. Otherwise, there's nothing to wait on and the "Buy" button will be enabled.
9. The user selects a shipping option and a shippingOptionChanged event is dispatched.
10. An event handler may optionally call send to send updated checkout details such as new calculated line items that include, eg: shipping, tax. Again, this information can be sent as a Promise, to enable the website to generate this information asynchronously. Similarly, request can also be called to request other information at this point (that depended on shipping option selection).
11. Once event dispatching has completed, if request was called, it will wait for its Promise to settle and then display the UI for whatever was requested this time, keeping the "Buy" button disabled. Otherwise, there's nothing to wait on and the "Buy" button will be enabled.
12. The user clicks "Buy" and the Promise for checkout.start resolves.
13. The webpage generates a payment request message and passes it to checkout.finish.
14. The browser UI shows the Payment App selection UI to complete the purchase.

So, the question is - do we want this sort of conversational API vs. the more rigid API proposed in the current spec?

[adrianba]

I don't like the .request().send().start().then() chaining API. It doesn't feel very familiar based on other platform APIs. So far I think we can say up front which options a web page needs without multiple calls to request() and (I think) the current updateWith method accomplishes the same as the send() method in response to interaction. I would prefer that we close this issue without making changes.

[adrianhopebailie]

This appears to simply be an issue of personal style in the design of the API. I have certainly seen both approaches in the wild but I believe the current design is more familiar in browser APIs.

To justify changing this design we'd need to see examples of how the API will likely be used by developers and evidence that the proposed design is easier to use than what we have today.

[adrianhopebailie]

Generic design question that would be better raised again as a concrete proposal now that the API shape has matured