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, 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 service.
38 the listener's 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.
69 The remote service recovers a YADIS document from the profile URL, as
70 described in YADIS 1.0.
72 The remote service looks for the URIs of Service of these types:
74 http://openmicroblogging.org/protocol/0.1/requestToken
75 Request Token URL, as in OAuth 1.0
77 http://openmicroblogging.org/protocol/0.1/userAuthorization
78 User Authorization URL, as in OAuth 1.0
80 http://openmicroblogging.org/protocol/0.1/accessToken
81 Access Token URL, as in OAuth 1.0
83 http://openmicroblogging.org/protocol/0.1/postNotice
84 Post Notice URL, as defined below.
86 http://openmicroblogging.org/protocol/0.1/updateProfile
87 Update Profile URL, as defined below.
89 http://openmicroblogging.org/protocol/0.1/identifier
90 identifier URI for the user with this profile URL.
92 If any of the URIs is unavailable, the remote service MUST stop
98 The remote service must go through the OAuth 1.0 dance to get
99 authorization to post notices and update profiles.
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,
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.
114 The remote service uses the defined requestToken URL to get a request
117 In the request token HTTP request, the remote service MUST send the
118 following additional parameter(s):
121 'http://openmicroblogging.org/protocol/0.1'
123 The identifier URI for the listener.
125 In the results for the request token request, the local service MUST
126 send the following additional parameters:
129 'http://openmicroblogging.org/protocol/0.1'
134 In requesting user authorization, the remote service must send the
135 following parameters:
138 'http://openmicroblogging.org/protocol/0.1'.
140 The identifier URI for the listener.
142 The identifier URI for the listenee.
144 The profile URL of the listenee.
145 omb_listenee_nickname
146 The nickname of the listenee.
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.
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.
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
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.
171 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
174 The local service, in a successful response, must return the
175 following additional parameters:
178 'http://openmicroblogging.org/protocol/0.1'.
179 omb_listener_nickname
180 A nickname for the listener.
182 The profile URL for the listener, possibly cleaned up or
185 It should return as many of the following as possible:
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
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.
199 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
202 This will allow the remote service to display information about the
203 listener in the listenee's "listeners" or "subscribers" list.
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
214 'http://openmicroblogging.org/protocol/0.1'.
216 The identifier URI for the listenee.
220 The content of the notice. No maximum, but 140 chars is recommended.
222 The message may include the following parameters:
225 The URL of the notice, if the notice is retrievable.
227 The URL of the license for the notice, if different from the
228 listenee's default license.
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.
239 License for the attached data. May be distinct from the notice's
240 license (if they're passing along someone else's content).
242 The local service should include the following parameters in its
246 'http://openmicroblogging.org/protocol/0.1'.
248 The local service makes no guarantees about the delivery of the notice
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]_
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.
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.
274 The message must use OAuth authorization. The message must also
275 include the following parameters:
278 'http://openmicroblogging.org/protocol/0.1'.
280 The identifier URI for the listenee.
282 The message may include any of the following parameters:
285 The profile URL of the listenee.
286 omb_listenee_nickname
287 The nickname of the listenee.
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.
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.
301 URL of a 96px by 96px image in PNG, GIF or JPEG format representing
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.