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