doc/openmicroblogging.txt

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