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.
17 To allow users of one microblogging service to publish notices to
18 users of another service, given the other users' permission.
23 Depends on OAuth 1.0, OAuth Discovery 1.0, YADIS 1.0.
25 We piggy-back additional information onto these protocols to pass
26 microblogging information back and forth.
36 to allow a remote service to send notices to the user's local
37 service on a remote user's behalf.
41 the user sending notices.
43 the listenee's microblogging service.
45 the listener's microblogging service.
47 "home" URL for the listener, typically their profile page on a
50 An alphanumeric short name for a person, 1-64 characters.
52 A globally unique and unchanging identifying URI for a user.
53 Need not be an URL. [*]_
55 A unique and unchanging identifier for a notice. Need not be an
58 .. [*] May be the profile URL, if it's defined not to change or be
59 re-used. The profile URL of some services includes the nickname,
60 and some let the user change his/her nickname. This user's profile
61 URL may change from 'http://example.net/~john' to
62 'http://example.net/~johnsmith' A tag URI, like
63 'tag:example.net,2008:user:1' may be more appropriate here.
64 .. [*] IWBNI the notice URI is used everywhere the notice is
65 published; for example, in any RSS feeds.
70 The user submits their profile URL [*]_ to the remote service somehow --
71 for example, with an HTML form on the remote service's Web site.
73 .. [*] For OAuth Discovery, this is the "protected resource". It may
74 be more correct that the protected resource is the postNotice URL
75 (see below), but the listener will be more familiar with their own
76 profile URL. So there will have to be discovery of the postNotice
77 URL anyways, and it might as well all be done in one step.
82 The remote service recovers a YADIS document from the profile URL, as
83 described in OAuth Discovery.
85 The request token service must have a LocalID associated with it,
86 containing the identifier URI for the listener.
88 The following two extra services must be included in the YADIS
89 document, with accompanying URIs.
91 http://openmicroblogging.org/protocol/0.1/postNotice
92 Post Notice URL, as defined below.
94 http://openmicroblogging.org/protocol/0.1/updateProfile
95 Update Profile URL, as defined below.
97 If any of the URIs is unavailable, the remote service MUST stop
103 The remote service must go through the OAuth 1.0 dance to get
104 authorization to post notices and update profiles.
106 In all OAuth, the consumer key should be the root URL for the
107 microblogging service, if available. The secret should be the blank
108 string (''), unless the remote server and local service have negotiated
109 another key. Such negotiation is out-of-scope for this document, and we
110 assume an "open" network of microblogging services. But if you want to
111 have that kind of network, do it with this key.
113 The remote service MUST do OAuth for every new listener, regardless of
114 whether they've already received authorization for posting to the
115 given postNotice URL. See `Posting a Notice`_ below.
120 The remote service uses the defined requestToken URL to get a request
123 In the request token HTTP request, the remote service MUST send the
124 following additional parameter(s):
127 'http://openmicroblogging.org/protocol/0.1'
129 The identifier URI for the listener.
131 In the results for the request token request, the local service MUST
132 send the following additional parameters:
135 'http://openmicroblogging.org/protocol/0.1'
140 In requesting user authorization, the remote service must send the
141 following parameters:
144 'http://openmicroblogging.org/protocol/0.1'.
146 The identifier URI for the listener.
148 The identifier URI for the listenee.
150 The profile URL of the listenee.
151 omb_listenee_nickname
152 The nickname of the listenee.
154 The default license URL for the listenee's stream. Typically the
155 URL of a Creative Commons license, with the Attribution license
156 being heavily encouraged. CC0 quitclaim also pretty good. The
157 local service MAY reject listenees if their licenses are
158 incompatible with the service.
160 The remote service should send as many of the following parameters as
161 possible. This will help the user decide if they really want to allow
162 the listening to happen, and allow the local service to store a copy
163 of the listenee's profile.
165 omb_listenee_fullname
166 The full name of the listenee. Up to 255 chars.
167 omb_listenee_homepage
168 The home page of the listenee (may be distinct from the profile
171 A brief biography of the listenee; less than 140 chars.
172 omb_listenee_location
173 Physical location of the listenee; less that 255 chars. No fixed
174 structure, but "Locality, Region, Country" or "Locality, Country"
175 or "Locality, Region" recommended.
177 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
180 The local service, in a successful response, must return the
181 following additional parameters:
184 'http://openmicroblogging.org/protocol/0.1'.
185 omb_listener_nickname
186 A nickname for the listener.
188 The profile URL for the listener, possibly cleaned up or
191 It should return as many of the following as possible:
193 omb_listener_fullname
194 The full name of the listener. Up to 255 chars.
195 omb_listener_homepage
196 The home page of the listener (may be distinct from the profile
199 A brief biography of the listener; less than 140 chars.
200 omb_listener_location
201 Physical location of the listener; less that 255 chars. No fixed
202 structure, but "Locality, Region, Country" or "Locality, Country"
203 or "Locality, Region" recommended.
205 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
208 This will allow the remote service to display information about the
209 listener in the listenee's "listeners" or "subscribers" list.
214 The access token step of the OAuth protocol requires no additional
220 To post a notice to the local service, the remote service sends an HTTP
221 POST message to the postNotice URL discovered above. The message must
222 use OAuth authorization. The message must also include the following
226 'http://openmicroblogging.org/protocol/0.1'.
228 The identifier URI for the listenee.
232 The content of the notice. No maximum, but 140 chars is recommended.
234 The message may include the following parameters:
237 The URL of the notice, if the notice is retrievable.
239 The URL of the license for the notice, if different from the
240 listenee's default license.
242 URL of additional content for the notice; for example, an image,
243 video, or audio file.
244 omb_seealso_disposition
245 One of 'link' or 'inline', to recommend how the extra data should
246 be shown. Default 'link'.
247 omb_seealso_mediatype
248 Internet Media Type of the see-also data. Advisory, probably
249 shouldn't be trusted.
251 License for the attached data. May be distinct from the notice's
252 license (if they're passing along someone else's content).
254 The local service should include the following parameters in its
258 'http://openmicroblogging.org/protocol/0.1'.
260 The local service makes no guarantees about the delivery of the notice
263 The remote service SHOULD NOT send a message with the same notice URL
264 to the same postNotice URL more than once. [*]_ If the request returns
265 a 403 Unauthorized message, the remote service SHOULD NOT post
266 messages to the same URL again with the same listenee, until another
267 listener has gone through the OAuth dance. [*]_
269 .. [*] A half-assed optimization. A local service may have a lot of
270 listeners listening to the same listenee. It would be pointless to
271 have the remote service post the same notice 100 times to the same
272 service. However, if the local service wants fine-grained control,
273 it can have a different postNotice URL for each listener.
274 .. [*] If there's one postNotice URL per listener, the 403 message
275 means the listener has told the local service not to allow posting
276 any more ("unsubscribed"). If there's one postNotice URL per local
277 service, it means that the count of listeners has dropped to 0.
282 If the listenee's profile information changes, the remote service MAY
283 send an HTTP POST message to to the updateProfile URL to tell the
284 local service about the change.
286 The message must use OAuth authorization. The message must also
287 include the following parameters:
290 'http://openmicroblogging.org/protocol/0.1'.
292 The identifier URI for the listenee.
294 The message may include any of the following parameters:
297 The profile URL of the listenee.
298 omb_listenee_nickname
299 The nickname of the listenee.
301 The default license URL for the listenee's stream. A change in the
302 default license only applies to future notices; notices previous
303 to the update SHOULD be treated as under the old license.
304 omb_listenee_fullname
305 The full name of the listenee. Up to 255 chars.
306 omb_listenee_homepage
307 The home page of the listenee.
309 A brief biography of the listenee; less than 140 chars.
310 omb_listenee_location
311 Physical location of the listenee; less that 255 chars.
313 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
316 Missing parameters should not be construed to mean that the profile
317 field has been blanked. The remote service MUST set the parameter to
318 an empty string to show that the field is blank.
323 * OAuth: http://oauth.net/
324 * OAuth Discovery: http://oauth.net/discovery/1.0
325 * XRDS Simple: http://xrds-simple.net/core/1.0/