TODOs and docs and openmicroblogging spec

Moved around a few TODOs.

Linked to docs in the foot menu better.

Added a specification for the openmicroblogging standard.

darcs-hash:20080522172006-84dde-060372ec90444faf0e3453229cfd33aceaf28e4a.gz
This commit is contained in:
Evan Prodromou 2008-05-22 13:20:06 -04:00
parent b2903983bd
commit 21d54452a0
3 changed files with 350 additions and 22 deletions

View File

@ -46,9 +46,9 @@
+ fix layout of textarea + fix layout of textarea
+ make notices into "big links" + make notices into "big links"
+ RSS 1.0 feeds of a user's notices + 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 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 - FOAF dump for user
- license on showstream - license on showstream
- license on shownotice - license on shownotice
@ -62,46 +62,50 @@
- add a next page link to showstream - add a next page link to showstream
- add a next page link to public - add a next page link to public
- add a next page link to all - add a next page link to all
- source link in footer menu + source link in footer menu
- public stream link in top menu + public stream link in top menu
- about doc
- help doc
- privacy doc
- source doc
- AGPL notification - AGPL notification
- gettext - gettext
- pretty URLs - pretty URLs
+ dump, fix, undump database
- subscribe remote
- add subscriber remote
- send remote notice
- receive remote notice
- release 0.2 - release 0.2
- Automatically linkify URLs in notices - Automatically linkify URLs in notices
- RDF dump of entire site - tinyurl-ification of URLs
- use only canonical email addresses - use only canonical email addresses
- license per notice - license per notice
- allow mixed-case usernames - allow mixed-case usernames
- allow non-latin usernames - allow non-latin usernames
- store canonical username for comparison and fetch - store canonical username for comparison and fetch
- site logo
- set Last-Modified - set Last-Modified
- XML sitemap generation - XML sitemap generation
- themes
- theme per site - theme per site
- theme per profile - theme per profile
- email confirmation for registration - email confirmation for registration
- change cookie handling for anon users to be more cache-friendly - 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 - 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 interface language
- content negotiation for content type - content negotiation for content type
- content negotiation for encoding - content negotiation for encoding
- content negotiation for charset - content negotiation for charset
- If-Modified-Since support - If-Modified-Since support
- Vary - Vary
- delete a notice - site logo
- release 0.3 - 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 - @ messages
- # tags - # tags
- L: location - L: location
@ -124,8 +128,8 @@
- release 0.5 - release 0.5
- Twitter-compatible API - Twitter-compatible API
- Pownce-compatible API - Pownce-compatible API
- include twitter subscriptions - include twitter subscriptions (push and pull)
- include Pownce subscriptions - include Pownce subscriptions (push and pull)
- privacy - privacy
- Wrap DB_DataObject with memcached caching layer - Wrap DB_DataObject with memcached caching layer
- login throttle to prevent brute-force attacks - login throttle to prevent brute-force attacks

323
doc/openlisten.txt Normal file
View File

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

View File

@ -172,8 +172,7 @@ function common_license_block() {
function common_head_menu() { function common_head_menu() {
$user = common_current_user(); $user = common_current_user();
common_element_start('ul', array('id' => 'menu', 'class' => ($user) ? 'five' : 'three')); common_element_start('ul', array('id' => 'menu', 'class' => ($user) ? 'five' : 'three'));
common_menu_item(common_local_url('doc', array('title' => 'help')), common_menu_item(common_local_url('public'), _t('Public'));
_t('Help'));
if ($user) { if ($user) {
common_menu_item(common_local_url('all', array('nickname' => common_menu_item(common_local_url('all', array('nickname' =>
$user->nickname)), $user->nickname)),
@ -202,6 +201,8 @@ function common_foot_menu() {
_t('Help')); _t('Help'));
common_menu_item(common_local_url('doc', array('title' => 'privacy')), common_menu_item(common_local_url('doc', array('title' => 'privacy')),
_t('Privacy')); _t('Privacy'));
common_menu_item(common_local_url('doc', array('title' => 'source')),
_t('Privacy'));
common_element_end('ul'); common_element_end('ul');
} }