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