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 you want to build something to run a MOOC, you will need to use the following parts of P2PU:
- Authentication
- User profiles
- Activity
- Notifications
- Messaging
- Badges
User story
So lets think up a little about a user story:You go to mooc.org and see a mooc that you like - "The study of geographic and temporal art as encountered in urban environments - SOGTA". You decide to sign up for the MOOC. When you click on sign-up you get redirected to P2PU to sign-in to your P2PU profile. Once you signed in, you are asked by P2PU if you want to allow mooc.org to send you notifications and publish activities to your activity feed?
Once you confirm you are redirected back to mooc.org. You am now signed up for SOGTA with your P2PU profile. On mooc.org you can participate in group discussions. Whenever you get a reply to a message that you posted in a discussion, you receive an email in your inbox. When you reply to the email, your message is also posted in the group discussion thread.
Every week you receive an email from the MOOC organizer that informs you what's happening with SOGTA.
On mooc.org there is a list of courses that is relevant to SOGTA. You 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, you receive a SOGTA participation badge to show that you completed the MOOC. This badge is shown on your profile at P2PU, but it's stored in your open badge backpack.
Prototype
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/username', '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/username to the list of users that signed up for the MOOC. mooc.org also sends a message to https://p2pu.org/username to give the user instructions about SOGTA
https://api.p2pu.org/send-message POST {'user-profile':'https://p2pu.org/username', '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/username', '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@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:
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.
So start thinking about how you would like to use an API to interact with P2PU and what you will build and send it to us at p2pu-dev@lists.p2pu.org
