A Social API (and Federation Protocol) Proposal

Hello, all.

I'd like to table a proposal for our social API and Federation Protocol 
specifications. This is very much a work in progress draft; you'll find 
lots of todo notes, and areas which are missing the detailed description 
they deserve.  There will be typos, spelling mistakes, incomplete 
sentences, etc. However, it has reached a point where I feel it is ready 
for commentary and critique.

So, let me introduce to you ActivityPump, so called because it 
originally derived from the pump.io protocol. It has diverged from that 
slightly. The main areas of change are:

  * Changes introduced by AS1 to AS2 churn
  * I'm reworking the authorization system significantly. Pump.io builds
    around OAuth 1.0, which causes trouble in the federated landscape.
    I'm working from the building blocks of OAuth 2.0 which lets the
    client on your mobile phone identify itself as myself.example to
    friendsite.example.
  * Consensus seems to be a more resource-oriented model, so I are
    aiming in that direction. What that means is that to update an
    object, you do an authenticated HTTP PUT to it, whilst in pump.io
    you post an update activity (actually, you should be able to do the
    PUT to in pump.io. in ActivityPump, its' the only way). I'm aiming
    for that as much as possible (a few cases don't work that way, and
    can't without great difficulty: the verbs "post", "like", "unlike",
    "follow" and "unfollow")
  * I've introduced a concept of "notification". Notification fixes a
    few issues with pump.io, namely that sometimes replies don't go to
    everyone (because of recipients you can't see and other reasons). If
    delivery is the forward channel (i.e. like a push-based RSS
    subscription), notification is the back channel (i.e. like
    WebMention or pingback).

Some areas of iffiness:

  * It would be nice to make the public collection a part of the AS2
    ontology.
  * I've used the HTTP NOTIFY method to implement the notification
    backchannel for federated servers. This originaly comes from SSDP, a
    part of UPnP, which I believe is an expired internet draft. Their
    use is the weird case of "multicast UDP HTTP" anyway, so I'm not
    concerned about conflict, but I am slightly wary of extending HTTP
    in this manner and of this causing implementation difficulties
    (poorly supported by frameworks and languages?).
  * Can the notification back channel and the delivery forward channel
    be unified? This probably makes implementations more complex
    (because now on receiving a notify you need to parse the incoming
    object's recipient list) and also causes more HTTP requests in
    general (I now need to go out and read all the recipient collections..)
  * There are a lot of todos!

In spite of these things, I think its' time for us to open up comments. 
One of the things I'm strongly leaning towards is minimum viable 
product, and I think things are going pretty well in that direction. My 
goal is to, as I think should be done with every specification, have the 
minimum complexity possible for the required functionality and no less

You can find the specification here:
http://oshepherd.github.io/activitypump/ActivityPump.html

     Owen