1 ===============================
2 OpenMicroBlogging specification
3 ===============================
10 To allow users of one microblogging service to publish notices to
11 users of another service, given the other users' permission.
16 Depends on OAuth 1.0, OAuth Discovery 1.0, YADIS 1.0.
18 We piggy-back additional information onto these protocols to pass
19 microblogging information back and forth.
29 to allow a remote service to send notices to the user's local
30 service on a remote user's behalf.
34 the user sending notices.
36 the listenee's microblogging service.
38 the listener's microblogging service.
40 "home" URL for the listener, typically their profile page on a
43 An alphanumeric short name for a person, 1-64 characters.
45 A globally unique and unchanging identifying URI for a user.
46 Need not be an URL. [*]_
48 A unique and unchanging identifier for a notice. Need not be an
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.
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.
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.
75 The remote service recovers a YADIS document from the profile URL, as
76 described in OAuth Discovery.
78 The request token service must have a LocalID associated with it,
79 containing the identifier URI for the listener.
81 The following two extra services must be included in the YADIS
82 document, with accompanying URIs.
84 http://openmicroblogging.org/protocol/0.1/postNotice
85 Post Notice URL, as defined below.
87 http://openmicroblogging.org/protocol/0.1/updateProfile
88 Update Profile URL, as defined below.
90 If any of the URIs is unavailable, the remote service MUST stop
96 The remote service must go through the OAuth 1.0 dance to get
97 authorization to post notices and update profiles.
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,
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.
112 The remote service uses the defined requestToken URL to get a request
115 In the request token HTTP request, the remote service MUST send the
116 following additional parameter(s):
119 'http://openmicroblogging.org/protocol/0.1'
121 The identifier URI for the listener.
123 In the results for the request token request, the local service MUST
124 send the following additional parameters:
127 'http://openmicroblogging.org/protocol/0.1'
132 In requesting user authorization, the remote service must send the
133 following parameters:
136 'http://openmicroblogging.org/protocol/0.1'.
138 The identifier URI for the listener.
140 The identifier URI for the listenee.
142 The profile URL of the listenee.
143 omb_listenee_nickname
144 The nickname of the listenee.
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.
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.
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
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.
169 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
172 The local service, in a successful response, must return the
173 following additional parameters:
176 'http://openmicroblogging.org/protocol/0.1'.
177 omb_listener_nickname
178 A nickname for the listener.
180 The profile URL for the listener, possibly cleaned up or
183 It should return as many of the following as possible:
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
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.
197 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
200 This will allow the remote service to display information about the
201 listener in the listenee's "listeners" or "subscribers" list.
206 The access token step of the OAuth protocol requires no additional
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
218 'http://openmicroblogging.org/protocol/0.1'.
220 The identifier URI for the listenee.
224 The content of the notice. No maximum, but 140 chars is recommended.
226 The message may include the following parameters:
229 The URL of the notice, if the notice is retrievable.
231 The URL of the license for the notice, if different from the
232 listenee's default license.
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.
243 License for the attached data. May be distinct from the notice's
244 license (if they're passing along someone else's content).
246 The local service should include the following parameters in its
250 'http://openmicroblogging.org/protocol/0.1'.
252 The local service makes no guarantees about the delivery of the notice
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]_
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.
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.
278 The message must use OAuth authorization. The message must also
279 include the following parameters:
282 'http://openmicroblogging.org/protocol/0.1'.
284 The identifier URI for the listenee.
286 The message may include any of the following parameters:
289 The profile URL of the listenee.
290 omb_listenee_nickname
291 The nickname of the listenee.
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.
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.
305 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
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.
315 * OAuth: http://oauth.net/
316 * OAuth Discovery: http://oauth.net/discovery/1.0
317 * XRDS Simple: http://xrds-simple.net/core/1.0/