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

On 8 July 2015 at 03:45, Manu Sporny <msporny@digitalbazaar.com> wrote:

> 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.
>

No, I understand what you mean by REST or RESTful.

We don't seem to have agreement on who the parties are to this standard or
what the communications flow will likely be between them.

My view is that we are going to focus on a message format for (possibly) 4
basic messages:
- Payment initiation request (from the payee to the payer)
- Payment initiation response (from the payer back to the payee)
- Payment completion request (from the payee to the payer)
- Payment completion response (from the payer back to the payee)

The delivery mechanism of this standardised message (likely a JSON document
with a schema defined by the standard) will not always be the same. The
request messages will originate (in most cases) as calls into the WebIDL
API hosted by the user agent and the responses will be returned as
responses to this API call (likely through a JavaScript promise pattern).

The user agent will select the delivery mechanism for the message based on
the type of wallet it is configured to use; native, cloud-based or even
embedded in the browser or OS.

For native wallets I hope that we will define, as a minimum, a best
practice for how user agents specify that wallets provide an interface to
receive this message and return a response. UA vendors may choose to do
this through existing mechanisms like extensions or they may come up with
something new, this is the value of having many of them involved. This is
not entirely new territory for them, they have managed to expose APIs
already that are proxies for external services like location.

For cloud-based wallets I'd expect the interface to be as simple as the
WebIDL API. A single URL endpoint to which messages can be sent and from
which responses will be returned. I guess this would qualify as a RESTful
API as you say.

For embedded wallets I think we cannot define this interface but should
expect wallets to take as input the standard request message formats we
define and return as output the standard response message formats we define.

>
>
> > 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.
>

I concede this is a requirement as I mentioned above. I guessit just felt
wrong to call a single endpoint that takes no parameters (just a standard
message format) as input an API but strictly speaking you are correct.


> 2. The merchant storefront service that accepts payment completion
>    messages from the payment processor service via the user agent.
>

Here I disagree. The response from the wallet will be proxied via the user
agent to the payee as a response to the WebIDL API call.


>
> 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).
>

This will be scheme specific and I don't think is a candidate for
standardization.

I can imagine a scenario where a scheme defines that for wallets to process
transactions using instruments for that scheme they must call out to some
external service as part of the process. Given the standardized flow we
will define the scheme can then specify where in the flow this must happen
and all the details about how and the message format etc.

I think a good candidate would be for a card scheme that supports
tokenisation. After the payment initiation request has been received and
the user has picked the card to use the scheme may specify that the wallet
must issue a call to some external service to get a transaction or merchant
specific token which is then passed back to the payee in the payment
initiation response.


>
> > 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.
>

+1

Although I;d like us to also find a way for this to also work as an
inter-app communication using something like custom URL protocols or
similar so that the same flow and messaging can be re-used when, for
example, the UA is a mobile browser and the
wallet is another app on the mobile.

I'm not suggesting that the same delivery mechanis must be used for both
scenarios but it would be gret if we also considered this one where it's
not possible to POST to another app.


>
> > 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.
>

Great!


>
> 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.
>

True, but I think that that history should be a warning against trying to
be too granular when we design any REST API. We should define what we have
to to ensure the delivery mechanism is consistent but the standardisation
should be in the flow and message format.


>
> > 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.
>

I disagree. The interface from a native wallet to the User Agent is not
something we should define as long as we specifiy that the UA proxies the
message received via the WebIDL API to the wallet without modification and
proxies the response back unchanged too.

The interface to the "merchant storefront service" (or any payee
application) is via the same WebIDL API.

Where I concede the API is required is in the case of cloud-based or hosted
wallets where the UA is passing the message it received via the WebIDL API
to a remote wallet service.

>
>
> 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.
>

I think we agree that 1 REST API is required for cloud-based wallets but
I'd like to hear if you think there are more.


> > 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.
>
>
True, but this doesn't change the fact that they don't need to be
standardised. It the payee's Web application that integrates into these
services. The messages we define will be received by the payee application
as responses to the WebIDL calls. Then the application must do whatever is
necessary to execute the payment via their payment service provider.

The good news is that once these messages are standardised I'd expect the
payment service providers to simply accept those messages directly with
minimal work required by the merchant application at all.


> > 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.
>

Ultimately there needs to be some service that is the interface from the UA
that has received the payment initiation request to the service or services
that process it and return a response. To my mind this service should be a
wallet AND as I have mentioned before should be capable (if required) to
also be an aggregator of multiple other child wallets.

I think we are talking about the same thing but using different
terminology. I see a wallet as a pretty hollow and useless entity until it
has at least one payment instrument in it.

If we are supporting cloud based wallets, how would they register
themselves with the browser if not via a WebIDL API? If you are expecting
the browser to keep a record of all instruments that register themselves
then the browser becomes way too important to this process in my opinion.
If the browser proxies this registration request to another service then
what is that service if not a wallet? (it's the "put a new card in your
wallet" metaphor)


>
> > 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?
>

Out of scope for v1. We only expect wallets to be able to accept the
message formats we define and return the response formats we define. In v1
that means that "support" is binary.

We could, in v2 have more granular definitions of what is supported or
leave this to be defined in the messages. Wallets that don't support a
certain feature will ignore the message content that they don't understand.
People won't use those wallets for long so we are promoting a system
whereby fair competition between wallets will drive innovation.


>
> > 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.
>

That's how they do it today, what's different? If the bank wants people to
use their wallet they need to come up with a better wallet than PayPal.
This way we achieve the ultimate goal of standardisation, anyone that tries
to lock participants out will be rejected by the market. If my bank somehow
prevents other wallets from storing their card (hard to imagine given that
this is mostly in the control of the card schemes) I'm not likely to keep
using my bank's card online, especially if I'd like to host my own wallet
(which I also hope will be a common scenario).


>
> > 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.
>

Looking forward to the call on Thursday!


>
> -- 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/
>
>
>