1 ===============================
2 OpenMicroBlogging specification
3 ===============================
5 :Author: Evan Prodromou (Control Yourself, Inc.)
6 :Contact: evan@controlezvous.ca
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.
20 To allow users of one microblogging service to publish notices to
21 users of another service, given the other users' permission.
26 Depends on OAuth 1.0, OAuth Discovery 1.0, YADIS 1.0.
28 We piggy-back additional information onto these protocols to pass
29 microblogging information back and forth.
39 to allow a remote service to send notices to the user's local
40 service on a remote user's behalf.
44 the user sending notices.
46 the listenee's microblogging service.
48 the listener's microblogging service.
50 "home" URL for the listener, typically their profile page on a
53 An alphanumeric short name for a person, 1-64 characters.
55 A globally unique and unchanging identifying URI for a user.
56 Need not be an URL. [*]_
58 A unique and unchanging identifier for a notice. Need not be an
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.
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.
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.
85 The remote service recovers a YADIS document from the profile URL, as
86 described in OAuth Discovery.
88 The request token service must have a LocalID associated with it,
89 containing the identifier URI for the listener.
91 The following two extra services must be included in the YADIS
92 document, with accompanying URIs.
94 http://openmicroblogging.org/protocol/0.1/postNotice
95 Post Notice URL, as defined below.
97 http://openmicroblogging.org/protocol/0.1/updateProfile
98 Update Profile URL, as defined below.
100 If any of the URIs is unavailable, the remote service MUST stop
106 The remote service must go through the OAuth 1.0 dance to get
107 authorization to post notices and update profiles.
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.
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.
123 The remote service uses the defined requestToken URL to get a request
126 In the request token HTTP request, the remote service MUST send the
127 following additional parameter(s):
130 'http://openmicroblogging.org/protocol/0.1'
132 The identifier URI for the listener.
134 In the results for the request token request, the local service MUST
135 send the following additional parameters:
138 'http://openmicroblogging.org/protocol/0.1'
143 In requesting user authorization, the remote service must send the
144 following parameters:
147 'http://openmicroblogging.org/protocol/0.1'.
149 The identifier URI for the listener.
151 The identifier URI for the listenee.
153 The profile URL of the listenee.
154 omb_listenee_nickname
155 The nickname of the listenee.
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.
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.
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
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.
180 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
183 The local service, in a successful response, must return the
184 following additional parameters:
187 'http://openmicroblogging.org/protocol/0.1'.
188 omb_listener_nickname
189 A nickname for the listener.
191 The profile URL for the listener, possibly cleaned up or
194 It should return as many of the following as possible:
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
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.
208 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
211 This will allow the remote service to display information about the
212 listener in the listenee's "listeners" or "subscribers" list.
217 The access token step of the OAuth protocol requires no additional
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
229 'http://openmicroblogging.org/protocol/0.1'.
231 The identifier URI for the listenee.
235 The content of the notice. No maximum, but 140 chars is recommended.
237 The message may include the following parameters:
240 The URL of the notice, if the notice is retrievable.
242 The URL of the license for the notice, if different from the
243 listenee's default license.
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.
254 License for the attached data. May be distinct from the notice's
255 license (if they're passing along someone else's content).
257 The local service should include the following parameters in its
261 'http://openmicroblogging.org/protocol/0.1'.
263 The local service makes no guarantees about the delivery of the notice
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. [*]_
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.
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.
289 The message must use OAuth authorization. The message must also
290 include the following parameters:
293 'http://openmicroblogging.org/protocol/0.1'.
295 The identifier URI for the listenee.
297 The message may include any of the following parameters:
300 The profile URL of the listenee.
301 omb_listenee_nickname
302 The nickname of the listenee.
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.
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.
316 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
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.
326 * OAuth: http://oauth.net/
327 * OAuth Discovery: http://oauth.net/discovery/1.0
328 * XRDS Simple: http://xrds-simple.net/core/1.0/