[p2pu-dev] P2PU API user story

Thu Jun 7 12:04:13 UTC 2012

Hi everyone

We've had some thoughts, some talk, and even the start of an
implementation for a P2PU API. It seems like everyone agrees that it's
a good idea and something that we need, but currently we are lacking
concrete use cases (maybe because we don't have the complete API yet -
a bit of a chicken and egg problem).

So I propose that we start by building a few prototypes of what we
would like to use an API for. A prototype doesn't need to be a running
program, although a running prototype would be great! We just need
something a little bit more tangible to help us think about the ideal
API that we want for P2PU.

A prototype may look something like this:

Lets say I want to build something to run a MOOC, I'll need to use the
following parts of P2PU:
- Authentication
- User profiles
- Activity
- Notifications
- Messaging
- Badges

So lets think a little about a user story:

I go to mooc.org and see a mooc that I like - "The study of geographic
and temporal art as encountered in urban environments - SOGTA". I
decide to sign up for the MOOC. When I click on sign-up I get
redirected to P2PU to sign-in to my P2PU profile. Once I signed in,
I'm asked by P2PU if I want to allow mooc.org to send me notifications
and publish activities to my activity feed?

Once I confirm I am redirected back to mooc.org. I am now signed up
for SOGTA with my P2PU profile. On mooc.org I can participate in group
discussions. Whenever I get a reply to a message that I posted in a
discussion, I receive an email in my inbox. When I reply to the email,
my message is also posted in the group discussion thread.

Every week I receive an email from the MOOC organizer that informs me
what's happening with SOGTA.

On mooc.org there is a list of courses that is relevant to SOGTA. I
can participate in these courses together with other people that is
also signed up for SOGTA. There is also lots of references to other
learning resources like coursera.

Finally, after participating in the MOOC, I receive a SOGTA
participation badge to show that I completed the MOOC. This badge is
shown on my profile at P2PU, but it's stored in my open badge
backpack.

Interaction between mooc.org and p2pu.org may look like this:

When someone at mooc.org creates a new MOOC, the MOOC gets published
to the course register at p2pu.org:

https://api.p2pu.org/courses PUT {'title': 'The study of geographic
and temporal art as encountered in urban environments', 'shortcode':
'SOGTA', 'signup-url':'mooc.org/sogta/sign-up', 'course-style':'MOOC',
 'tags':['art','geo-art'], ... }

Now the "The study of geographic and temporal art as encountered in
urban environments" will show up when someone searches for "geographic
art" on the P2PU course register!

https://api.p2pu.org/courses also support GET,POST and DELETE to
query, update and delete courses from the course register

When a user signs up for a MOOC on mooc.org, the browser will be
redirected to https://p2pu.org/login. After the user successfully
logged in, they get a token and user profile from p2pu.org and that is
passed onto mooc.org (handled by javascript without the user knowing
anything about it). mooc.org then does a post to

https://api.p2pu.org/user/verify-login POST
{'user-profile':'https://p2pu.org/dirk',
'token':'bd46c283195c0aefaffb179f6197f18d184d38b8'}

which respons with 200 OK to indicate that the user is logged in and
that the token is valid.

mooc.org can now safely add https://p2pu.org/dirk to the list of users
that signed up for the MOOC. mooc.org also sends a message to
https://p2pu.org/dirk to give him instructions about SOGTA

https://api.p2pu.org/send-message POST
{'user-profile':'https://p2pu.org/dirk', 'subject':'Welcome to SOGTA',
'content':'We are glad that you joined SOGTA ...' }

p2pu.org automatically add 'app':'mooc.org' to the data and depending
on the user's preferences is sent a message to the email address
registered with p2pu.org

Whenever a significant action is performed in SOGTA by a user,
mooc.org does the following:

https://api.p2pu.org/activity PUT {'subject':'https://p2pu.org/user',
'verb':'post', 'object':'https://mooc.org/sogta',
'verb-url':'https://mooc.org/sogta/comment/135', 'message':'user
posted a comment in the MOOC SOGTA'}

This is only allowed if user gave permission to mooc.org to post
activity. If this failed mooc.org may choose to do

https://api.p2pu.org/activity PUT {'verb':'post',
'object':'https://mooc.org/sogta',
'verb-url':'https://mooc.org/sogta/comment/135', 'message':'A new
comment was posted in the MOOC SOGTA'}

https://api.p2pu.org/activity GET {'noun':'https://p2pu.org/user'} -
will return all activities involving user

https://api.p2pu.org/activity GET {'noun':'https://mooc.org/sogta'} -
will return all activities involving SOGTA

When a user makes a comment and receives a reply, something like this
can happen:

https://api.p2pu.org/notification PUT
{'profile':'https://p2pu.org/username', 'subject':'[SOGTA] reply to
comment', 'message':'Someone replied to your comment',
'email-reply-possible':'True'}

This call returns
{'reply-token':'005f035e7d1b1c2ff6de0d4a73cc2f040d5b4127'} to mooc.org

The user receives an email if notifications are allowed for mooc.org.
The email look like this:

From: reply+005f035e7d1b1c2ff6de0d4a73cc2f040d5b4127 at reply.p2pu.org
Subject: [mooc.org] [SOGTA] reply to comment
Message:
Someone replied to your comment.

You can respond by replying to this email with your text:
<here>
</here>

When the user replies to the email, mooc.org gets a post from p2pu.org
at the URL that mooc.org had to supply when registering to use the
P2PU API:

https://mooc.org/api/message-in PUT {'from':'https://p2pu.org/user',
'reply-token':'005f035e7d1b1c2ff6de0d4a73cc2f040d5b4127',
'message':'???'}

I haven't yet thought through the badge API for this scenario.

This email turned out to be rather long, so I posted it on my blog
(http://disfunksioneel.blogspot.com/2012/06/p2pu-api-story.html) to
make it slightly more readable.

Now it's your turn!

Cheers
d

ps. I'll by beer for anyone that can figure out where the tokens come
from. You'll have to be in Berlin during July to get your beer :)