*[08/11/2003: A copy of this spec can be found
here
courtesy of Dave Winer. I also posted one
here.]Really Simple Discovery is a way to help client software find the services needed to read, edit, or "work with" weblogging software. Although I talk about weblogging software, there's no reason this format can't apply to other forms of web client/system software that I wasn't considering, or may not even exist as of this writing. (There is an
example below
where I did just that.) This format is simple but flexible. One of the deisgn goals was to ensure that it would be human writeable. This was my \"test" for ensuring that the format was easy for everyone to implement.
The goal is simple. To reduce the information required to UserName, Password, and homepage URL.
Hopefully, it'll work for you.
"mysig"
PS For early adopters there is a
BDG for moving from 0.6 to 1.0. Thanks for jumping in.
***The ProblemThe number one customer service issue I've had with "Archipelago" is settings for services. Specifically, the "Path To Service" setting, but more generally where to point for services.
"I'm afraid I could not get very far with Archipelago. The download and install was fine, but I'm not sure what to set for the rest. I have my account with blogger (that I use now) and the site itself is hosted somewhere else. Both of these have different names and passwords. What do I do?"
The solution I propose below will simplify the discovery of settings information by reducing the information a user must supply to three well known elements. Assuming that the
RSD
file is generated by the blogging software (Radio, Manila, Moveable Type, SnipSnap, Conversant, Drupal, etc.) the other required bits of information not well known to the user can be easliy discovered and supplied.
***Examples of differenceBlogger has "plant.blogger.com", "api/RPC2", and the blogID. The "Path to Service is case sensitive. If a user enters "/api/rpc2" in their preferences they get an error in html, courtesy of Tomcat, that states "The requested resource (/rpc2) is not available.". The error message is subject to change in format. This same problem could apply to every case.
Moveable Type uses an endpoint of "mt/mt-xmlrpc.cgi", and the domain level of the URL depends on the installation. The site identifier is the blogID number.
Manila and Radio use "rpc2", case insensitive. Manila's domain level URL depends on the installation but it does provide the "sitename" through the ManilaRPC API. Whew! Radio has a consistent siteID (as of this writing).
Conversant has its own API plus support for basic Blogger API. It uses x|x|x identifier where the various flexible elements of Conversant are "x". Familiarity with Conversant is somewhat required. These elements are also required when specifiying a message, so you need a message "number" that looks like this x|x|x|123. Path to service is rpc2, and case insensitive (not tested).
As you can imagine, plenty of folks have struggled to get this information exactly correct for each case. Anything that helps automate the process or gives users up to date information on the specific service their employing would help mitigate this difficulty.
***RSDI'd think that something simple, like an xml document that lists the critical info would be about right. It should be simple enough to be written by hand.
I'm calling this document "Really Simple Discoverability". I want to address the needs of blogging software, not be terribly general at first, and leave room for growth. I hope the RSS and XML folks dive in and help create a great format.
The goal is to reduce the information required to set up editing software to three well known elements. UserName, Password, and homepage URL. Any other critical bits should either be defined in the related RSD file, or discoverable using the information provided.
***Location, Location, LocationJon Udell
provided another piece to the puzzle, reminding me about the RSS link we have buried in our homepages. A similar link would serve the purpose here. This idea as it relates to RSS (I believe) was first proposed by
Mark Pilgrim. It works perfectly here as well.
By inserting a link such this
<link rel="EditURI" type="application/rsd+xml" title=\"RSD" href="http:\//whereever the rsd.xml lives." />
into a homepage's header we uncouple the need to know where to find the RSD file. Each vendor can control where it makes sense for them to "place" the RSD file, accessible via the embedded URL. Client software only need to look at the homepage headers to discover where to look for more information. Excellent.
At the same time, it has been suggested that we have a "best practice" location that represents a location where clients can try to find the file in cases where the link above has been removed, broken, or simply is not present. Having surveyed where folks are keeping their RSS files, we recommend http:\//www.userdomain.com/rsd.xml
(There can be validation issues with the closed form (<something />) as shown above, which is important for say XHMTL but not for HTML 4.01 Transitional. The link will work just as well either way.)
***Elements<service> is a container element. It's a hedge against the future.
Sub-elements of <service>
- <engineName> a string that is the name of the engine that is providing the services being described.
- <engineLink> is the URL to the home of the engine.
- <homePageLink> is the URL of the users homepage.
- <apis> is a container element.
Sub-elements of <apis>
- <api> has 4 required attributes. "name" is a string that is the name of the api. There is a list of "well-known" names below. A name does not need to be listed here or elsewhere to be valid. (see below). Multiple api elements are allowed.
- "preferred" is a boolean and takes either "true" or "false". The point is to allow weblog software to list all the APIs supported, but choose which one to "recommend" to the client software. Only one API should set as prefered.
- "apiLink" is the URL for this API. The location the client should speak to.
- "blogID" is a common bit of data that most APIs currently require. It can be specified here. If your system doesn't require it, include the attribute, but leave it blank like so blogID="" (this is demonstrated in the example.)
Optional sub-elements of <api>
The api element doesn't require these elements. Information required by more flexible or capable systems can be expressed here.
<settings> is a container element and is required if you are going to include the following optional sub-elements.
- <docs> is a URL that points to the documentation for this API.
- <notes> is text that should be used to explain features and their settings. Intended to be human readable.
- <setting> requires a single attribute "name" a string which refers to the name of the "service-specific-setting". The value is the service setting. Multiple setting elements are allowed.
***Well known API namesThe well known names are a list of
suggested
names at the time of publication (Wednesday, December 18, 2002). Being listed in this table is
not
required for an api name to be included in a valid RSD document. Further, we recommend that, if possible, you look to the api name implemented by the creator of that api as the definitive "name". (What is implemented is real.) To suggest additions, please use the form below. (It's broken at the moment, sorry.) (Atom (AtomPub) was added as requested
here. Tuesday, October 16, 2007)
- Atom
- Blogger
- MetaWeblog
- Conversant
- Manila
- MetaWiki
- Antville
- LiveJournal
***Example RSDExample 1Here is
an early example
of an RSD file for the RESTLog API.
***Extending RSDDevelopers are welcome to extend RSD using modules defined in namespaces, as
specified by the W3C.
A RSD feed may contain elements not described on this page, only if those elements are defined in a namespace. All core RSD elements are defined in a namespace. Below is an example that extends RSD to include two additional elements generatorAgent and errorReportsTo. Another example can be found
further down the page.
Example (optional module)***Down the road, down the wayExtension and modification should occur via modules. This should provide enough flexibility for anyone to extend the format in the direction they require.
Backward compatibility
must be maintained by any future versions.
As an example I wrote
a module
for
Dave's weblog archives format.
Everyone wants easy access to archives! And it displays how RSD can be flexible about its purpose.
****ThanksStephan Schmidt,
Seth Dillingham,
Brent Simmons, and
Dave Winer
have all lent a hand in getting this together. Their support and ideas are greatly appreciated.
I also would like to thank all the developers who decided to join the fun and implement RSD prior to 1.0. It really helped other developers understand what RSD is accomplishing.
***Changes
- Wiped the changes clean (they're
archived)
***Notes
***ContactFeel free to
write.
***Copyright and disclaimer© Copyright 2002 Circumstance Technology. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and these paragraphs are included on all such copies and derivative works.
This document may not be modified in any way, such as by removing the copyright notice or references to Circumstance Technology or other organizations. Further, while these copyright restrictions apply to the written RSD specification, no claim of ownership is made by Circumstance Technology to the format it describes. Any party may, for commercial or non-commercial purposes, implement this format without royalty or license fee to Circumstance Technology. The limited permissions granted herein are perpetual and will not be revoked by Circumstance Technology or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and CIRCUMSTANCE TECHNOLOGY DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
***Trust*We respect your privacy. We'll NEVER sell or rent your email address. Ever. We require it only to ensure that real suggestions are added to the list. Thanks for understanding.
Edit in Archipelago.