Re: PaySwarm Alpha 3 released

On 08/09/2012 02:48 PM, Melvin Carvalho wrote:
> PaySwarm Alpha 3 was released today.
> 
> Congrats, really impressive stuff.

Thanks! It's been many, many hard years of work to get to this point.
Dave Longley and Dave Lehn are largely to thank for the technical
implementation excellence that has gone into PaySwarm to date. We have
also had a huge help from the folks that are participating in this
group, the Linked Data community, the RDFa Working Group and the JSON-LD
Working Group. :)

> Here are the major changes:
> 
> * REST API documentation * https://dev.payswarm.com/docs
> 
> So the docs look great, well organized, simple, easy to follow.

Good to hear... we'll get more docs up as the weeks go on... things have
been churning too quickly over the past 15 months for us to produce
solid documentation, but now that we're pushing towards
commercialization, we're trying to really zero in on the v1.0 REST APIs.

> One question I had was why there are two .well-known 'config' files:

We had originally placed all PaySwarm Authority config values in a file
called /payswarm-config-v1. We then changed it to
/.well-known/linked-data-services, but that seemed to get push-back from
a few of the Linked Data and IETF folks I pinged. They suggested that we
use a different /.well-known/ file for each class of application. With
that input, and since splitting the Web Keys stuff out of the PaySwarm
spec, we thought that it would be better to have a two separate
locations for the configuration endpoints:

1) The Web Keys REST API configuration endpoint under:
   /.well-known/web-keys
2) The PaySwarm REST API configuration endpoint under:
   /.well-known/payswarm

As you found out, this is what you get when you hit the Web Keys REST
API config endpoint at /.well-known/web-keys:

> { "@context": "http://purl.org/payswarm/v1", "publicKeyService": 
> "https://dev.payswarm.com/i?form=register" }

The JSON-LD context really should be
  "@context": "http://purl.org/web-keys/v1",

How to use this endpoint is loosely described in the Web Keys spec (the
spec really needs to be updated now that we've settled on a good way to
register public keys):

http://payswarm.com/specs/source/web-keys/

You basically construct a GET request to that URL and tack on the public
key that you would like to associate with your account on the server.
The server creates a location for the key (exposed as Linked Data - RDFa
and possibly JSON-LD in the future), and returns the Web Key URL for
your public key.

The second endpoint that you hit was /.well-known/payswarm, which gave
you this:

> { "@context": "http://purl.org/payswarm/v1", "id": 
> "https://dev.payswarm.com/", "authorityIdentity": 
> "https://dev.payswarm.com/i/authority", "publicKey": 
> "https://dev.payswarm.com/i/authority/keys/1", "contractService": 
> "https://dev.payswarm.com/contracts", "licenseService": 
> "https://dev.payswarm.com/licenses", "paymentService": 
> "https://dev.payswarm.com/transactions?form=pay", 
> "vendorRegistrationService": 
> "https://dev.payswarm.com/i?form=register" }

If you will notice, this is describing the Linked Data object
"https://dev.payswarm.com/" (which is the website). Here's a brief
description of each key in that object:

authorityIdentity - This is the agent in charge of the website. PaySwarm
calls a "login account" a "profile". Each "profile" can have one or more
identity (some real-world identity such as "Melvin Carvalho", some
anonymous such as "d38af73b38"). The identity is the thing that acts on
your behalf - it's a software agent that digitally signs contracts,
exchanges messages, etc. The authorityIdentity field tells REST clients
who has ultimate authority on the website.

publicKey - This is the authorityIdentity's public key, which is used to
verify digital signatures, generate encrypted messages, etc.

contractService - we're probably getting rid of this and replacing it
with transactionService - which is the location that you HTTP POST all
transactions to (monetary transfers, signed digital contracts, deposits,
withdrawals, etc.):
https://dev.payswarm.com/docs?topic=services.transaction.postPurchaseRequest

licenseService - this is a service that PaySwarm clients can use to
retrieve license information. Without getting into the details,
generating the proper cryptographic hashes for licenses is not very
straight forward, so we expose a service that offloads that work to
PaySwarm Authorities.

paymentService - this is the service that any vendor should re-direct
the buyer to in order to complete the transaction via a UI. This service
is typically used on the first interaction between the buyer and the
vendor. After the first transaction, the buyer can choose to setup a
budget with the vendor, at which point the vendor can do direct-debits
from the buyer's account (up to a certain limit) without bothering the
buyer. This budget mechanism is how in-app purchases are accomplished.

vendorRegistrationService - used by any vendor when they would like to
register with their PaySwarm Authority. This typically registers a
public key (note that the URL endpoint for the Web Keys publicKey
service and this service are the same). The reason that we have two
different service entries for Web Keys and vendor registration is
because we were thinking of including other information along with the
registration (like the label of the public key, preferences, etc.). This
stuff is still in the air... the main thing preventing us from combining
the two services into one is because they may do two fairly different
things in the future.

Since I'm having to explain this in an e-mail to a mailing list... I
think these endpoints should be the next candidates that we document.

> The first one I was expecting some kind of key and it gave me the 
> gateway to register.  The 2nd one I was expecting a config, but the 
> key PEM ( https://dev.payswarm.com/i/authority/keys/1 ) was there

Yeah, I can see how that is confusing. Do you have any ideas of how we
could document it differently? Perhaps a high-level overview of working
with a PaySwarm Authority? A primer?

> This by no means a criticism, just as a noob trying to understand the
> intuition behind it ...

No, please - criticize! We really need folks like you taking a look at
the setup and letting us know what doesn't work for you. Knowing that
there was confusion over those two endpoints is good, because it lets us
know that we really need to improve those areas.

https://github.com/web-payments/payswarm.com/issues/1
https://github.com/web-payments/payswarm.com/issues/2

Was there anything I said above that wasn't clear? I'm trying to
understand how you're learning about the system so that we can make sure
the things that were missing for you are not missing for others coming
in behind you.

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny)
Founder/CEO - Digital Bazaar, Inc.
blog: Which is better - RDFa Lite or Microdata?
http://manu.sporny.org/2012/mythical-differences/

Received on Saturday, 11 August 2012 02:41:18 UTC