|
RFC: Really Simple Discoverability
Thu, Oct 31, 2002; by Daniel Berlinger.
*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.
The Problem
The 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, etc.) the other required bits of information not well known to the user can be easliy discovered and supplied.
Examples of difference
Blogger 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.
RSD
I'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, Location
Jon 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
Elements
<service> is a container element. It's a hedge against the future.
Sub-elements of <service>
- <engineName> 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" contains the name of the api. There is a list of "well-known" names below. Multiple api elements is allowed.
- "preferred" is a boolean and takes either "true" or "false". The point is to be allow the 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.
- "rpcLink" is the URL for this API. The location the client should speak to.
- "blogID" is a common bit of data that most API 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. They are intended to be human readable.
- <setting> takes an required attribute "name" which refers to the name of the "service-specific-setting". The value is the service setting. Multiple setting elements is allowed.
Well known API names
In order to maximize the usefulness of the api name attribute, it is necessary to have a suggestion of how to refer to the various APIs. Folks call them various things, and truthfully, I'd like to hear from the author of the API as to how they'd like their work refered. Of course, anyone can suggest additions. Importantly, not being listed in this table doesn't mean you can't create an RSD api element for the API of your choice. We're just trying to make client development straightforward.
- Blogger
- MetaWeblog
- Conversant
- ManilaRPC
- MetaWiki
- Antville
- LiveJournal
Example RSD
Example 1
Extending RSD
Developers 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 way
I expect that once we hit 1.0, the version will freeze. I want to leave room for developers to have input early on, to make sure that the core is complete. After that, extension 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 a useful 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.
*
Thanks
Stephan Schmidt,
Seth Dillingham, and
Brent Simmons
have all lent a hand in getting this together. Their support and ideas are greatly appreciated.
Changes
- Friday, December 13, 2002:
LiveJournal
added to WK list.
- Monday, December 2, 2002: Added clarity to defining a single prefered API.
- Monday, December 2, 2002: Added clarity to need for backward compatibility.
- Wednesday, November 27, 2002: Added TOC
- Wednesday, November 27, 2002: Added forms for well known api name submissions and general suggestions
Notes
Contact
Feel free to write. Suggestions are welcome.
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.
comment
|
