diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/TODO | 44 | ||||
| -rw-r--r-- | doc/openlisten.txt | 323 |
2 files changed, 347 insertions, 20 deletions
@@ -46,9 +46,9 @@ + fix layout of textarea + make notices into "big links" + RSS 1.0 feeds of a user's notices -- RSS 1.0 feeds of a user's notices + friends ++ RSS 1.0 feeds of a user's notices + friends + RSS 1.0 dump of a user's notices -- RSS 1.0 feed of all public notices ++ RSS 1.0 feed of all public notices - FOAF dump for user - license on showstream - license on shownotice @@ -62,46 +62,50 @@ - add a next page link to showstream - add a next page link to public - add a next page link to all -- source link in footer menu -- public stream link in top menu ++ source link in footer menu ++ public stream link in top menu +- about doc +- help doc +- privacy doc +- source doc - AGPL notification - gettext - pretty URLs ++ dump, fix, undump database +- subscribe remote +- add subscriber remote +- send remote notice +- receive remote notice - release 0.2 - Automatically linkify URLs in notices -- RDF dump of entire site +- tinyurl-ification of URLs - use only canonical email addresses - license per notice - allow mixed-case usernames - allow non-latin usernames - store canonical username for comparison and fetch -- site logo - set Last-Modified - XML sitemap generation +- themes - theme per site - theme per profile - email confirmation for registration - change cookie handling for anon users to be more cache-friendly -- subscribe remote -- add subscriber remote -- send remote notice -- receive remote notice -- confirmation email -- tinyurl-ification of URLs - jQuery for as much as possible -- themes -- RDFa for stream pages -- RDFa for subscriber pages -- RDFa for subscribed pages -- plugins and hooks - content negotiation for interface language - content negotiation for content type - content negotiation for encoding - content negotiation for charset - If-Modified-Since support - Vary -- delete a notice +- site logo - release 0.3 +- RDF dump of entire site +- delete a notice +- plugins and hooks +- RDFa for stream pages +- RDFa for subscriber pages +- RDFa for subscribed pages - @ messages - # tags - L: location @@ -124,8 +128,8 @@ - release 0.5 - Twitter-compatible API - Pownce-compatible API -- include twitter subscriptions -- include Pownce subscriptions +- include twitter subscriptions (push and pull) +- include Pownce subscriptions (push and pull) - privacy - Wrap DB_DataObject with memcached caching layer - login throttle to prevent brute-force attacks diff --git a/doc/openlisten.txt b/doc/openlisten.txt new file mode 100644 index 000000000..b3208c24f --- /dev/null +++ b/doc/openlisten.txt @@ -0,0 +1,323 @@ +=============================== +OpenMicroBlogging specification +=============================== + +Version 0.1 + +Purpose +======= + +To allow users of one microblogging service to publish notices to +users of another service, given the other users' permission. + +Enabling technologies +===================== + +Depends on OAuth 1.0, YADIS 1.0. + +We piggy-back additional information onto these protocols to pass +microblogging information back and forth. + +Terminology +=========== + +microblogging service + undefined. +user + undefined. +listen + to allow a remote service to send notices to the user's local + service on a remote user's behalf. +listener + the person listening. +listenee + the user sending notices. +remote service + the listenee's service. +local service + the listener's service. +profile URL + "home" URL for the listener, typically their profile page on a + microblogging site. +nickname + An alphanumeric short name for a person, 1-64 characters. +identifier URI + A globally unique and unchanging identifying URI for a user. + Need not be an URL. [*]_ +notice URI + A unique and unchanging identifier for a notice. Need not be an + URL. [*]_ + +.. [*] May be the profile URL, if it's defined not to change or be + re-used. The profile URL of some services includes the nickname, + and some let the user change his/her nickname. This user's profile + URL may change from 'http://example.net/~john' to + 'http://example.net/~johnsmith' A tag URI, like + 'tag:example.net,2008:user:1' may be more appropriate here. +.. [*] IWBNI the notice URI is used everywhere the notice is + published; for example, in any RSS feeds. + +Initiation +========== + +The user submits their profile URL to the remote service somehow -- +for example, with an HTML form on the remote service's Web site. + +Discovery +========= + +The remote service recovers a YADIS document from the profile URL, as +described in YADIS 1.0. + +The remote service looks for a service of this type: + + http://openmicroblogging.org/protocol/0.1 + +The service must include the following 5 URLs. [*]_ + +omb:requestToken + Request Token URL, as in OAuth 1.0 + +omb:userAuthorization + User Authorization URL, as in OAuth 1.0 + +omb:accessToken + Access Token URL, as in OAuth 1.0 + +omb:postNotice + Post Notice URL, as defined below. + +omb:updateProfile + Update Profile URL, as defined below. + +It must also include the following URI: + +omb:identifier + identifier URI for the user with this profile URL. + +Here, omb: is the namespace prefix for: + + http://openmicroblogging.org/xmlns/0.1 + +The YADIS URI defined for the service can be ignored. + +.. [*] I decided to use a separate namespace with 5 elements to enable + having different providers for general OAuth and specific OµB. A + future version of this document may have a mode that allows a + single URL defined in the <URI> element with an additional URL + parameter like 'action=requesttoken', 'action=userauthorization' or + something similar. But that simplifies the YADIS doc at the expense + of the rest of the protocol. + +Authorization +============= + +The remote service must go through the OAuth 1.0 dance to get +authorization to post notices and update profiles. + +In all OAuth, the consumer key should be blank (''), unless the remote +server and local service have negotiated another key. Such negotiation +is out-of-scope for this document, and we assume an "open" network of +microblogging services. But if you want to have that kind of network, +do it with this key. + +The remote service MUST do OAuth for every new listener, regardless of +whether they've already received authorization for posting to the +given postNotice URL. See `Posting a Notice`_ below. + +Request token +------------- + +The remote service uses the defined requestToken URL to get a request +token. + +In the request token HTTP request, the remote service MUST send the +following additional parameter(s): + +omb_version + 'http://openmicroblogging.org/protocol/0.1' +omb_listener + The identifier URI for the listener. + +In the results for the request token request, the local service MUST +send the following additional parameters: + +omb_version + 'http://openmicroblogging.org/protocol/0.1' + +User authorization +------------------ + +In requesting user authorization, the remote service must send the +following parameters: + +omb_version + 'http://openmicroblogging.org/protocol/0.1'. +omb_listener + The identifier URI for the listener. +omb_listenee + The identifier URI for the listenee. +omb_listenee_profile + The profile URL of the listenee. +omb_listenee_nickname + The nickname of the listenee. +omb_listenee_license + The default license URL for the listenee's stream. Typically the + URL of a Creative Commons license, with the Attribution license + being heavily encouraged. CC0 quitclaim also pretty good. The + local service MAY reject listenees if their licenses are + incompatible with the service. + +The remote service should send as many of the following parameters as +possible. This will help the user decide if they really want to allow +the listening to happen, and allow the local service to store a copy +of the listenee's profile. + +omb_listenee_fullname + The full name of the listenee. Up to 255 chars. +omb_listenee_homepage + The home page of the listenee (may be distinct from the profile + URL). +omb_listenee_bio + A brief biography of the listenee; less than 140 chars. +omb_listenee_location + Physical location of the listenee; less that 255 chars. No fixed + structure, but "Locality, Region, Country" or "Locality, Country" + or "Locality, Region" recommended. +omb_listenee_avatar + URL of a 96px by 96px image in PNG, GIF or JPEG format representing + the listenee. + +The local service, in a successful response, must return the +following additional parameters: + +omb_version + 'http://openmicroblogging.org/protocol/0.1'. +omb_listener_nickname + A nickname for the listener. +omb_listener_profile + The profile URL for the listener, possibly cleaned up or + canonicalized. + +It should return as many of the following as possible: + +omb_listener_fullname + The full name of the listener. Up to 255 chars. +omb_listener_homepage + The home page of the listener (may be distinct from the profile + URL). +omb_listener_bio + A brief biography of the listener; less than 140 chars. +omb_listener_location + Physical location of the listener; less that 255 chars. No fixed + structure, but "Locality, Region, Country" or "Locality, Country" + or "Locality, Region" recommended. +omb_listener_avatar + URL of a 96px by 96px image in PNG, GIF or JPEG format representing + the listener. + +This will allow the remote service to display information about the +listener in the listenee's "listeners" or "subscribers" list. + +Posting a Notice +================ + +To post a notice to the local service, the remote service sends an HTTP +POST message to the postNotice URL discovered above. The message must +use OAuth authorization. The message must also include the following +parameters: + +omb_version + 'http://openmicroblogging.org/protocol/0.1'. +omb_listenee + The identifier URI for the listenee. +omb_notice + The notice URI. +omb_notice_content + The content of the notice. No maximum, but 140 chars is recommended. + +The message may include the following parameters: + +omb_notice_url + The URL of the notice, if the notice is retrievable. +omb_notice_license + The URL of the license for the notice, if different from the + listenee's default license. +omb_seealso + URL of additional content for the notice; for example, an image, + video, or audio file. +omb_seealso_disposition + One of 'link' or 'inline', to recommend how the extra data should + be shown. Default 'link'. +omb_seealso_mediatype + Internet Media Type of the see-also data. Advisory, probably + shouldn't be trusted. +omb_seealso_license + License for the attached data. May be distinct from the notice's + license (if they're passing along someone else's content). + +The local service should include the following parameters in its +response: + +omb_version + 'http://openmicroblogging.org/protocol/0.1'. + +The local service makes no guarantees about the delivery of the notice +to anyone. + +The remote service SHOULD NOT send a message with the same notice URL +to the same postNotice URL more than once. [2]_ If the request returns +a 403 Unauthorized message, the remote service SHOULD NOT post +messages to the same URL again with the same listenee, until another +listener has gone through the OAuth dance. [3]_ + +.. [2] A half-assed optimization. A local service may have a lot of + listeners listening to the same listenee. It would be pointless to + have the remote service post the same notice 100 times to the same + service. However, if the local service wants fine-grained control, + it can have a different postNotice URL for each listener. +.. [3] If there's one postNotice URL per listener, the 403 message + means the listener has told the local service not to allow posting + any more ("unsubscribed"). If there's one postNotice URL per local + service, it means that the count of listeners has dropped to 0. + +Updating a profile +================== + +If the listenee's profile information changes, the remote service MAY +send an HTTP POST message to to the updateProfile URL to tell the +local service about the change. + +The message must use OAuth authorization. The message must also +include the following parameters: + +omb_version + 'http://openmicroblogging.org/protocol/0.1'. +omb_listenee + The identifier URI for the listenee. + +The message may include any of the following parameters: + +omb_listenee_profile + The profile URL of the listenee. +omb_listenee_nickname + The nickname of the listenee. +omb_listenee_license + The default license URL for the listenee's stream. A change in the + default license only applies to future notices; notices previous + to the update SHOULD be treated as under the old license. +omb_listener_fullname + The full name of the listener. Up to 255 chars. +omb_listener_homepage + The home page of the listener. +omb_listener_bio + A brief biography of the listener; less than 140 chars. +omb_listener_location + Physical location of the listener; less that 255 chars. +omb_listener_avatar + URL of a 96px by 96px image in PNG, GIF or JPEG format representing + the listener. + +Missing parameters should not be construed to mean that the profile +field has been blanked. The remote service MUST set the parameter to +an empty string to show that the field is blank. |