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