Re: [w3c/browser-payment-api] Migrate PaymentRequest text from arch to payment request spec. (#110)

@ianbjacobs wrote:
> People who want to understand how the parts fit together without reading WebIDL.

There is no WebIDL in "Section 4: The Payment Request API Architecture" and that section is the only section people will have to read if they want to get an overview of the Payment Request API Architecture. Here is a link to the changed version of the document:

http://manu.sporny.org/tmp/wpwg/browser-payment-api/specs/paymentrequest.html#the-payment-request-api-architecture

> It is rather that it may not have to change even as the API changes.

If it doesn't change as the API changes, then the text will remain the same (and not change). No extra work is needed.

> Or, we can augment it to fulfill new communications requirements without having to rev the API document which will be harder to do because of IPR commitments.

New communication requirements related to the Payment Request browser API will most likely require new documents. The purpose of the "The Payment Request API Architecture" section is to describe just that (the architecture of the Payment Request browser API)... and that is tightly bound to the browser API and the set of documents around the API that use WebIDL to express concepts. If you take a look at the diagram, you'll see all the specs are rooted on the Payment Request API document. This is a browser-only ecosystem.

I'm also asserting that we're not quite clear on the communication requirements for the "architecture.html" document and that placing the Payment Request API Architecture into that document muddies the waters and misleads readers into thinking that we're building a browser-only ecosystem. 

I assert that that we should have a "Web Payments Architecture" document that doesn't insinuate that we're building a browser-only ecosystem.

I'll also note that all the objects in all documents rooted at the Payment Request API Architecture are described in WebIDL, which is problematic when it comes to how to express these objects (such as a payment request) in the HTTP API. I'm assuming that these objects are not going to be expressed in WebIDL, but rather JSON and possibly JSON Schema. So, linking to specifications that only describe payment messages in WebIDL sends the wrong message, which is "this is a browser-only ecosystem", and that's a bad message to send out in an FPWD.

This PR attempts to constructively addresses these concerns above.



---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/browser-payment-api/pull/110#issuecomment-204560838