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