doc/openlisten.txt

   1 ===============================
   2 OpenMicroBlogging specification
   3 ===============================
   4
   5 Version 0.1
   6
   7 Purpose
   8 =======
   9
  10 To allow users of one microblogging service to publish notices to
  11 users of another service, given the other users' permission.
  12
  13 Enabling technologies
  14 =====================
  15
  16 Depends on OAuth 1.0, YADIS 1.0.
  17
  18 We piggy-back additional information onto these protocols to pass
  19 microblogging information back and forth.
  20
  21 Terminology
  22 ===========
  23
  24 microblogging service
  25     undefined.
  26 user
  27     undefined.
  28 listen
  29     to allow a remote service to send notices to the user's local
  30     service on a remote user's behalf.
  31 listener
  32     the person listening.
  33 listenee
  34     the user sending notices.
  35 remote service
  36     the listenee's service.
  37 local service
  38     the listener's service.
  39 profile URL
  40     "home" URL for the listener, typically their profile page on a
  41     microblogging site.
  42 nickname
  43     An alphanumeric short name for a person, 1-64 characters.
  44 identifier URI
  45     A globally unique and unchanging identifying URI for a user.
  46     Need not be an URL. [*]_
  47 notice URI
  48     A unique and unchanging identifier for a notice. Need not be an
  49     URL. [*]_
  50
  51 .. [*] May be the profile URL, if it's defined not to change or be
  52    re-used. The profile URL of some services includes the nickname,
  53    and some let the user change his/her nickname. This user's profile
  54    URL may change from 'http://example.net/~john' to
  55    'http://example.net/~johnsmith' A tag URI, like
  56    'tag:example.net,2008:user:1' may be more appropriate here.
  57 .. [*] IWBNI the notice URI is used everywhere the notice is
  58    published; for example, in any RSS feeds.
  59
  60 Initiation
  61 ==========
  62
  63 The user submits their profile URL to the remote service somehow --
  64 for example, with an HTML form on the remote service's Web site.
  65
  66 Discovery
  67 =========
  68
  69 The remote service recovers a YADIS document from the profile URL, as
  70 described in YADIS 1.0.
  71
  72 The remote service looks for a service of this type:
  73
  74     http://openmicroblogging.org/protocol/0.1
  75
  76 The service must include the following 5 URLs. [*]_
  77
  78 omb:requestToken
  79     Request Token URL, as in OAuth 1.0
  80
  81 omb:userAuthorization
  82     User Authorization URL, as in OAuth 1.0
  83
  84 omb:accessToken
  85     Access Token URL, as in OAuth 1.0
  86
  87 omb:postNotice
  88     Post Notice URL, as defined below.
  89
  90 omb:updateProfile
  91     Update Profile URL, as defined below.
  92
  93 It must also include the following URI:
  94
  95 omb:identifier
  96     identifier URI for the user with this profile URL.
  97
  98 Here, omb: is the namespace prefix for:
  99
 100     http://openmicroblogging.org/xmlns/0.1
 101
 102 The YADIS URI defined for the service can be ignored.
 103
 104 .. [*] I decided to use a separate namespace with 5 elements to enable
 105    having different providers for general OAuth and specific OµB. A
 106    future version of this document may have a mode that allows a
 107    single URL defined in the <URI> element with an additional URL
 108    parameter like 'action=requesttoken', 'action=userauthorization' or
 109    something similar. But that simplifies the YADIS doc at the expense
 110    of the rest of the protocol.
 111
 112 Authorization
 113 =============
 114
 115 The remote service must go through the OAuth 1.0 dance to get
 116 authorization to post notices and update profiles.
 117
 118 In all OAuth, the consumer key should be blank (''), unless the remote
 119 server and local service have negotiated another key. Such negotiation
 120 is out-of-scope for this document, and we assume an "open" network of
 121 microblogging services. But if you want to have that kind of network,
 122 do it with this key.
 123
 124 The remote service MUST do OAuth for every new listener, regardless of
 125 whether they've already received authorization for posting to the
 126 given postNotice URL. See `Posting a Notice`_ below.
 127
 128 Request token
 129 -------------
 130
 131 The remote service uses the defined requestToken URL to get a request
 132 token.
 133
 134 In the request token HTTP request, the remote service MUST send the
 135 following additional parameter(s):
 136
 137 omb_version
 138     'http://openmicroblogging.org/protocol/0.1'
 139 omb_listener
 140     The identifier URI for the listener.
 141
 142 In the results for the request token request, the local service MUST
 143 send the following additional parameters:
 144
 145 omb_version
 146     'http://openmicroblogging.org/protocol/0.1'
 147
 148 User authorization
 149 ------------------
 150
 151 In requesting user authorization, the remote service must send the
 152 following parameters:
 153
 154 omb_version
 155     'http://openmicroblogging.org/protocol/0.1'.
 156 omb_listener
 157     The identifier URI for the listener.
 158 omb_listenee
 159     The identifier URI for the listenee.
 160 omb_listenee_profile
 161     The profile URL of the listenee.
 162 omb_listenee_nickname
 163     The nickname of the listenee.
 164 omb_listenee_license
 165     The default license URL for the listenee's stream. Typically the
 166     URL of a Creative Commons license, with the Attribution license
 167     being heavily encouraged. CC0 quitclaim also pretty good. The
 168     local service MAY reject listenees if their licenses are
 169     incompatible with the service.
 170
 171 The remote service should send as many of the following parameters as
 172 possible. This will help the user decide if they really want to allow
 173 the listening to happen, and allow the local service to store a copy
 174 of the listenee's profile.
 175
 176 omb_listenee_fullname
 177     The full name of the listenee. Up to 255 chars.
 178 omb_listenee_homepage
 179     The home page of the listenee (may be distinct from the profile
 180     URL).
 181 omb_listenee_bio
 182     A brief biography of the listenee; less than 140 chars.
 183 omb_listenee_location
 184     Physical location of the listenee; less that 255 chars. No fixed
 185     structure, but "Locality, Region, Country" or "Locality, Country"
 186     or "Locality, Region" recommended.
 187 omb_listenee_avatar
 188     URL of a 96px by 96px image in PNG, GIF or JPEG format representing
 189     the listenee.
 190
 191 The local service, in a successful response, must return the
 192 following additional parameters:
 193
 194 omb_version
 195     'http://openmicroblogging.org/protocol/0.1'.
 196 omb_listener_nickname
 197     A nickname for the listener.
 198 omb_listener_profile
 199     The profile URL for the listener, possibly cleaned up or
 200     canonicalized.
 201
 202 It should return as many of the following as possible:
 203
 204 omb_listener_fullname
 205     The full name of the listener. Up to 255 chars.
 206 omb_listener_homepage
 207     The home page of the listener (may be distinct from the profile
 208     URL).
 209 omb_listener_bio
 210     A brief biography of the listener; less than 140 chars.
 211 omb_listener_location
 212     Physical location of the listener; less that 255 chars. No fixed
 213     structure, but "Locality, Region, Country" or "Locality, Country"
 214     or "Locality, Region" recommended.
 215 omb_listener_avatar
 216     URL of a 96px by 96px image in PNG, GIF or JPEG format representing
 217     the listener.
 218
 219 This will allow the remote service to display information about the
 220 listener in the listenee's "listeners" or "subscribers" list.
 221
 222 Posting a Notice
 223 ================
 224
 225 To post a notice to the local service, the remote service sends an HTTP
 226 POST message to the postNotice URL discovered above. The message must
 227 use OAuth authorization. The message must also include the following
 228 parameters:
 229
 230 omb_version
 231     'http://openmicroblogging.org/protocol/0.1'.
 232 omb_listenee
 233     The identifier URI for the listenee.
 234 omb_notice
 235     The notice URI.
 236 omb_notice_content
 237     The content of the notice. No maximum, but 140 chars is recommended.
 238
 239 The message may include the following parameters:
 240
 241 omb_notice_url
 242     The URL of the notice, if the notice is retrievable.
 243 omb_notice_license
 244     The URL of the license for the notice, if different from the
 245     listenee's default license.
 246 omb_seealso
 247     URL of additional content for the notice; for example, an image,
 248     video, or audio file.
 249 omb_seealso_disposition
 250     One of 'link' or 'inline', to recommend how the extra data should
 251     be shown. Default 'link'.
 252 omb_seealso_mediatype
 253     Internet Media Type of the see-also data. Advisory, probably
 254     shouldn't be trusted.
 255 omb_seealso_license
 256     License for the attached data. May be distinct from the notice's
 257     license (if they're passing along someone else's content).
 258
 259 The local service should include the following parameters in its
 260 response:
 261
 262 omb_version
 263     'http://openmicroblogging.org/protocol/0.1'.
 264
 265 The local service makes no guarantees about the delivery of the notice
 266 to anyone.
 267
 268 The remote service SHOULD NOT send a message with the same notice URL
 269 to the same postNotice URL more than once. [2]_ If the request returns
 270 a 403 Unauthorized message, the remote service SHOULD NOT post
 271 messages to the same URL again with the same listenee, until another
 272 listener has gone through the OAuth dance. [3]_
 273
 274 .. [2] A half-assed optimization. A local service may have a lot of
 275    listeners listening to the same listenee. It would be pointless to
 276    have the remote service post the same notice 100 times to the same
 277    service. However, if the local service wants fine-grained control,
 278    it can have a different postNotice URL for each listener.
 279 .. [3] If there's one postNotice URL per listener, the 403 message
 280    means the listener has told the local service not to allow posting
 281    any more ("unsubscribed"). If there's one postNotice URL per local
 282    service, it means that the count of listeners has dropped to 0.
 283
 284 Updating a profile
 285 ==================
 286
 287 If the listenee's profile information changes, the remote service MAY
 288 send an HTTP POST message to to the updateProfile URL to tell the
 289 local service about the change.
 290
 291 The message must use OAuth authorization. The message must also
 292 include the following parameters:
 293
 294 omb_version
 295     'http://openmicroblogging.org/protocol/0.1'.
 296 omb_listenee
 297     The identifier URI for the listenee.
 298
 299 The message may include any of the following parameters:
 300
 301 omb_listenee_profile
 302     The profile URL of the listenee.
 303 omb_listenee_nickname
 304     The nickname of the listenee.
 305 omb_listenee_license
 306     The default license URL for the listenee's stream. A change in the
 307     default license only applies to future notices; notices previous
 308     to the update SHOULD be treated as under the old license.
 309 omb_listener_fullname
 310     The full name of the listener. Up to 255 chars.
 311 omb_listener_homepage
 312     The home page of the listener.
 313 omb_listener_bio
 314     A brief biography of the listener; less than 140 chars.
 315 omb_listener_location
 316     Physical location of the listener; less that 255 chars.
 317 omb_listener_avatar
 318     URL of a 96px by 96px image in PNG, GIF or JPEG format representing
 319     the listener.
 320
 321 Missing parameters should not be construed to mean that the profile
 322 field has been blanked. The remote service MUST set the parameter to
 323 an empty string to show that the field is blank.