Re: PaySwarm Alpha 3 released

On 11 August 2012 04:40, Manu Sporny <msporny@digitalbazaar.com> wrote:

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

Thanks, very helpful ... I'm going to have a go at setting up the wordpress
plugin next then I'll let you know how I get on ...


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