WebIDL vs. REST APIs vs. Web APIs (was: Re: Web Payments Working Group Charter review (Manu))

On 07/07/2015 06:03 AM, Adrian Hope-Bailie wrote:
> I don't understand where these REST API's would be.

We have a definition mismatch on "REST API". When I used the term, I
mean "RESTful API" - meaning an API that follows REST architectural
constraints... which is a fancy way of saying - build it using the same
best practices that the Web is built on:

https://en.wikipedia.org/wiki/Representational_state_transfer

I don't think there's anything controversial there.

> Between which two entities? The only scenario I can think of is 
> between the browser and a cloud-wallet but that interaction doesn't 
> necessarily have to be implemented through a REST API.

There are at least two services that will have endpoints on different
servers that are not WebIDL interfaces:

1. The payment processor service (aka wallet service) that accepts
   payment requests for processing from a user agent.
2. The merchant storefront service that accepts payment completion
   messages from the payment processor service via the user agent.

In some other cases, the payment processor service may communicate
directly with the merchant processor service (such as in the case of
payee-initiated/pull payments).

> How do you imagine the browser passing this request to the wallet? I
>  would say a simple POST to that URL in a new Window is sufficient
> and the return from the cloud-wallet will be another call to the
> browser API (from within the wallet window).

Yep, that "POST to that URL" is a RESTful API (aka REST API). So is the
response to the merchant.

> I'm not sure of a precedent where a W3C WG has defined REST APIs and 
> I think that's because when you do you start to step outside the 
> scope of what we should be standardizing in this group.

Here's the precedent, a W3C standard that defines REST APIs:

http://www.w3.org/TR/2015/REC-ldp-20150226/

So, we're not in new territory and it has been done before at W3C.

The reason it hasn't been done very often until now is because the level
of abstraction that W3C has traditionally worked at did not include
application layer stuff (the stuff that Web developers do).

The Web Payments work is definitely application layer stuff, and so
defining RESTful APIs are in scope.

> We could come up with a more complex set of interactions but I don't
>  think we should assume that will be the case by mandating that we'll
>  define REST APIs.

I don't see how we address the goals of the Web Payments WG charter with
only WebIDL interfaces.

We need to standardize at least the messages and protocol between the
user agent and the payment processor service (aka wallet service) and
the user agent and the merchant storefront service.

We definitely can't use WebIDL to do that, as WebIDL only has to do w/
the interfaces exposed by the user agent.

So, we're left w/ REST APIs as the only other alternative (unless I'm
missing something).

> As discussed, I don't think it's appropriate to list a REST API 
> deliverable if we aren't certain one will be required. I'm not 
> convinced that we do need one but let's discuss on Thursday.

I'm certain and convinced, so I'll put it up as a discussion topic for
the Thursday call.

> The API's at payment service providers exist today. They are not 
> standardised because they don't need to be. They are specific to each
> payment scheme they implement.

They are specific to each payment service provider, not each payment
scheme. Braintree's mechanism to process a Visa credit card is different
from Square's, which is different from Stripe's, and so on and so on.

> The API's used by Websites will be the WebIDL interfaces exposed via
> the browser.

+1

> I think we should include a WebIDL API for registration so that
> there is a standard way for a wallet to request that it become the
> user's default wallet (scenario 1) and also for payment instruments
> to request inclusion in the wallet (scenario 2).

That's one way to go about solving the problem. Another is to only
provide a mechanism for registering payment instruments and have the
discovery mechanism capable of discovering all payment instruments
available to the person and re-directing them to the one that they
select, entirely bypassing the concept of a wallet.

> Scenario 1: I visit the PayPal website and PayPal can request that 
> they be my wallet. The browser asks me to choose Yes or No and also 
> allows me to disable these kinds of requests in future for this site 
> or all sites. I choose yes and my browser now registers 
> https://paypal.com/wallet/ahopebailie as my wallet endpoint.

How does one discover what features are available via the wallet? Does
it support coupon storage? Does it support receipt storage? What about
subscriptions?

> Scenario 2: I am on my bank's website and my bank requests that it 
> add my bank card to my wallet. My browser prompts me to add the card 
> and when I say Yes a request is proxied to the PayPal wallet endpoint
> to instruct PayPal to add the card to my wallet.

So, PayPal now controls the bank card payment experience? I don't think
banks would be thrilled about that.

> These need some further thought and discussion but probably not 
> before the WG takes this on and digs into the details.

Thinking through these things often helps refine the charter... and I
expect it's going to be some of the same people thinking through these
things /and/ participating in the Web Payments WG work.

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
Founder/CEO - Digital Bazaar, Inc.
blog: Web Payments: The Architect, the Sage, and the Moral Voice
https://manu.sporny.org/2015/payments-collaboration/

Received on Wednesday, 8 July 2015 01:45:35 UTC