TruerWords Logo
Google
 
Web www.truerwords.net

Search TruerWords

Welcome
Sign Up  Log On

Topic: RFC: Really Simple Discovery

Messages: (21) 1


Author: Seth Dillingham

Date:11/12/2002

Permalink Icon

# 2594

RFC: Really Simple Discovery

Daniel Berlinger posted an RFC a couple weeks ago called Really Simple Discovery. He's trying to design a communication between desktop weblog editor apps and weblog servers, to automate the configuration of the editor for a specific weblog.

There are lots of desktop apps out there now for editing your weblog with something other than a browser. Archipelago, written by Daniel, is one. Sid, by Steve Ivy, is another. Brent is working on NetNewsWire Pro, which will include an editor. Radio has built-in support for both the MetaWeblog and Blogger API's (as both the client and the server). The list goes on and on...

Every one of these apps needs to be configured for the weblog you want to edit, and that config info is formatted for the software that runs the weblog. There's no way to guess the config info for one weblog just by knowing the config for another on some other platform.

That's the problem Daniel is trying to solve, and it's one that needs to be solved. The servers know what they need to receive from these desktop weblog editors, so they might as well tell the app directly instead of forcing them to enter it all by hand.

I don't think the current RFC is complete enough, but it's a start and that's exactly what we need.

If you're working on an editor that would benefit from this, or even if you just use such an editor and would like to have the setup process be automated, please post your thoughts on Daniel's site. You could even post them here, if you prefer: I'll make sure he sees them.

[Top]


Author: Seth Dillingham

Date:11/14/2002

Permalink Icon

# 2597

RSD Notes

I told Daniel that I'd have comments on RSD. I'm really busy right now, but he's trying to get this off the ground (it's important to me, too) and I don't want to hold him up any (in case my opinion matters). So...

In order to define the format of the RSD document, you first need to define exactly what you want it to tell the client software.

Should it just say what API's are supported by the weblog?

After listing the supported API's, should it have sections for each supported API with the parameters that the client needs to send back?

It seems that the RSD document could provide the client software with everything it needs to know, except for security info (username and password).

Anyway, discussions of syntax and language are moot until there's some agreement on what the document should actually say. Anything else is putting the cart before the horse.

[Top]


Author: Daniel Berlinger

Date:11/14/2002

Permalink Icon

# 2598

RE: RSD Notes

>> Should it just say what API's are supported by the weblog?

I thought that the API most likely to work should be included and that was it. Stephan (of SnipSnap) thought all could be listed and one marked default (read "try first"). That's the way it looks now, although I'm thinking of changing it. I really want to keep the required elements very simple and straightforward and then let people create modules for whatever else they want.

>>After listing the supported API's, should it have sections for each supported API with the parameters that the client needs to send back?

>From the keep it simple side, I'd say no, let's define a module etc. for this. From the client dev side, I'd say I doubt I'd use this because there's more to hooking up to CMS than just the calls (as you know). It's more about UI decisions than calls for the most part. Looking this information up this way doesn't help me (but it might help others).

>>It seems that the RSD document could provide the client software with everything it needs to know, except for security info (username and password).

To which I'd add the site's URL.

The experience I'd like to build for Archipelago is where the user points it to the homepage of their site, and all the info except the two pieces you mention are filled in. At the moment the list isn't long and is encapsulated by the current format. (Whether its done right or wrong is kinda irrelevant, we'll get it straightened out before long.)

Is there something you think is sorely lacking? Because ultimately that's what we need to get to. The simplest format with the fewest bits of info that will serve the largest community.

Thanks,

d.

[Top]


Author: Seth Dillingham

Date:11/15/2002

Permalink Icon

# 2600

RE: RSD Notes

On 11/14/02, Daniel Berlinger said:


>>Should it just say what API's are supported by the weblog?
>
>I thought that the API most likely to work should be included and
>that was it. Stephan (of SnipSnap) thought all could be listed and
>one marked default (read "try first"). That's the way it looks now,
>although I'm thinking of changing it. I really want to keep the
>required elements very simple and straightforward and then let people
>create modules for whatever else they want.

In my opinion, it should list everything by default.

There are two questions involved in this handshake:

1. What protocols does the server support?

2. What protocols does the client support?

If the server hasn't been updated to support this handshake, then someone's going to be hand-writing this document to be served "statically" (ie, it's not being generated by logic on the server). If the server supports more than one protocol, the person writing the document is going to have to just pick the one he thinks is most likely to be used? Or the one he likes the best? What if the client making the connection doesn't support the one picked by the author of that document, but does support another protocol on the server? How will it find out about it?

There's already a lot of weblog-editing clients out there, and we know more are being written. The are lots of weblog servers, too.

If we're not going to produce a handshake protocol that at least solves *most* of the needs, then we're wasting out time.

I'm not proposing anything complex, I'm just saying that the handshake document should be able to specify all of the protocols supported by the server, and all of the parameters for each protocol that can be specified without sacrificing security.

Would a sample handshake document help here? I'm willing to put one together to demonstrate. ("Hand written!")


>>After listing the supported API's, should it have sections for each
>>supported API with the parameters that the client needs to send back?
>
>From the keep it simple side, I'd say no, let's define a module etc.
>for this. From the client dev side, I'd say I doubt I'd use this
>because there's more to hooking up to CMS than just the calls (as you
>know). It's more about UI decisions than calls for the most part.
>Looking this information up this way doesn't help me (but it might
>help others).

Now I'm confused.

I thought the problem we were trying to solve was this very configuration issue, which you're saying you wouldn't use.

It seems obvious to me (but I haven't written a client, so I could be wrong) that the two big issues (with configuring a client to use one of these protocols) are:

1. Which protocol to use

2. What parameters the server needs when submitting something via the protocol

Simply telling the client which protcol(s) you support doesn't solve the problem: the user still has to figure out what information is needed. As you said, this information is different for every server, even when using the same protocol.


>>It seems that the RSD document could provide the client software
>>with everything it needs to know, except for security info (username
>>and password).
>
>To which I'd add the site's URL.
>
>The experience I'd like to build for Archipelago is where the user
>points it to the homepage of their site, and all the info except the
>two pieces you mention are filled in. At the moment the list isn't
>long and is encapsulated by the current format. (Whether its done
>right or wrong is kinda irrelevant, we'll get it straightened out
>before long.)

Oops, now I'm confused again. You said in the previous section that you wouldn't use this, but others might, and now you're saying that you'd like to have "all the info ..." filled in.

Looking at your example document again, I see that you're just putting in the protocol values for the default right after the list of supported API's.

As I said above, that means that if the user's client doesn't support the default protocol, then the information provided in the handshake was useless.

All I'm suggesting is that -- instead of listing only the parameters for the default API (protocol) -- the format allow (not require) the params for all of the API's. Also, the params for the default API would be moved to a slightly different hierarchy. (Again, if you want an example...)

Seth

[Top]


Author: Daniel Berlinger

Date:11/15/2002

Permalink Icon

# 2601

RE: RSD Notes

>>>Would a sample handshake document help here? I'm willing to put one together to demonstrate. ("Hand written!")

You bet. Please do, thanks.

>>>Looking at your example document again, I see that you're just putting in the protocol values for the default right after the list of supported API's.

Actually not. More below.

>>>As I said above, that means that if the user's client doesn't support the default protocol, then the information provided in the handshake was useless.

>>>All I'm suggesting is that -- instead of listing only the parameters for the default API (protocol) -- the format allow (not require) the params for all of the API's. Also, the params for the default API would be moved to a slightly different hierarchy. (Again, if you want an example...)

Again, yes, an example would be great.

I think I misunderstood what you meant at first, and that has led to the confusion above. I think we're heading down the same road.

Let me just correct one thing. The protocol values are not for the default, but abstracted from all the APIs I've worked with so far. They all require almost every one of those elements -- "almost" with the exception being the service URL which has only been used by Blogger, but possibly could be used by others. All the other elements are needed by every API I've worked with...

That said, " my cup is empty"

d.

[Top]


Author: Seth Dillingham

Date:11/19/2002

Permalink Icon

# 2613

Sample RSD Document

Here's the sample RSD document that I promised Daniel I'd write.

It's still very simple, but it allows the parameter (setting) names to vary in the different APIs without having to define a really big vocabulary for the XML.

Updated 20nov2002 with optional documentation elements moved to the api elements.

[Top]


Author: Jim Roepcke

Date:11/20/2002

Permalink Icon

# 2614

Re: Sample RSD Document

On Tuesday, November 19, 2002, at 05:41 PM, Seth Dillingham wrote:

> Here's the sample RSD document
> <http://www.truerwords.net/2613/enclosure/RSD.xml> that I promised
> Daniel <http://archipelago.phrasewise.com/> I'd write.
>
> It's still very simple, but it allows the parameter (setting) names to
> vary in the different APIs without having to define a really big
> vocabulary for the XML.

Makes sense to me... Hopefully, Conversant (or any other CMS) would be
able to automatically generate that document correctly so I wouldn't
have to.

Jim

[Top]


Author: Seth Dillingham

Date:11/20/2002

Permalink Icon

# 2616

The "Value" of My RSD Approach...

Brent and Daniel are having a conversation about RSD on Daniel's site. Brent's planning to support something like RSD (hopefully RSD's final format) in NNW.

Brent's thoughts are that the document needs to be kept incredibly simple, but I don't understand why he's taking it so far. Our intent (or mine, anyway) is that these documents will be automatically produced in the handshake between server-side weblog software (Conversant, Manila, Blogger, etc.) and client-side software like Archipelago, Sid (if Steve ever gets involved), and NetNewsWire Pro.

Daniel has a space for the documentation, but it's in the head area. Brent wants it removed altogether. I would prefer to have it included as an optional element or property of the <api> element, and I've updated my sample RSD file to show that. Daniel's argument for the documentation link is a good one:

At least this way I can give them a button that will pop open the docs page for their blogging software.

That's a good enough explanation for me. If the documentation link isn't in the RSD file, then don't show the button. Simple.

I've been asked to explain the "value" of what I've proposed.

The main difference between my proposal and Daniel's is the description of the API's. Daniel's assumes that all weblog API's will use a common set of settings and has specified those in the top level of the document. Mine creates one api element for each supported api, and puts the settings for each API within child elements of the respective api element.

Also, the settings elements are all named "setting," and given a name attribute to specify what setting is being described.

The value of this approach is that an api can use any number of "settings," and they're all defined within the scope of the api's section of the RSD document. An API that is completely unrelated to the others (like Conversant's) can now provide any number of settings, all with different names, without adding to the namespace used by the XML document. This actually makes it very easy to provide a DTD for the RSD file, because all possible element names have been defined.

Yet with all that, it remains very simple.

(No, I don't expect a DTD to be needed for RSD files, but it doesn't hurt to be producing valid xml, does it?)

Now my question to Daniel and Brent is, what problem do you have with my approach? What doesn't it solve? Do you agree that our intent is to have these files produced by the weblog software, eventually?

[Top]


Author: Brent Simmons

Date:11/20/2002

Permalink Icon

# 2617

Re: The "Value" of My RSD Approach...

About keeping it maximally simple -- my approach when doing the first version of something like this is to have it do the absolute minimum that's needed. Then use that for a while, then based on that experience figure out what has to happen next.

That's why I'd tend to argue against, for instance, a docs link.

But I'm not some kind of crazy stickler -- implementability and consensus are more important than my personal opinions. Whatever we come up with is what I'll support. No problem.

While I could see paring a couple things from Seth's sample RSD document, to make it even simpler, it's not a big deal. I like especially that each API can have a separate service URL.

[Top]


Author: Brent Simmons

Date:11/20/2002

Permalink Icon

# 2618

Re: The "Value" of My RSD Approach...

>What doesn't it solve?

It solves the questions NetNewsWire has -- what APIs are supported, what's the blogID of a site, and what are the service URLs. Those are the hard things to configure, and those are answered here.

>Do you agree that our intent is to have these files produced by the weblog software, eventually?

Absolutely, yes, completely, totally, indeed.

Sooner rather than later would be my preference.

Another issue -- how do we discover the discovery? Daniel mentioned the idea of having a link embedded in one's home page, just as we have a link that points to the RSS file (for RSS discovery). This works for me -- it means you'd point your weblog editor to the home page of your site, your editor would find the link to the rsd document, it would read the rsd document, then it would configure itself. That's exactly the kind of user experience one wants.

[Top]


Author: Seth Dillingham

Date:11/20/2002

Permalink Icon

# 2619

RE: The "Value" of My RSD Approach...

On 11/20/02, Brent Simmons said:

>Another issue -- how do we discover the discovery? Daniel mentioned
>the idea of having a link embedded in one's home page, just as we
>have a link that points to the RSS file (for RSS discovery). This
>works for me -- it means you'd point your weblog editor to the home
>page of your site, your editor would find the link to the rsd
>document, it would read the rsd document, then it would configure
>itself. That's exactly the kind of user experience one wants.

I haven't mentioned it because I completely agreed with that approach from the beginning. It seems obvious.

We also might want to have some "best practice" standard place to put the RSD document. If a site doesn't have the link tag yet (in at least some server-side weblog tools, it will require a modification to the templates), the client can still try to find the document on its own.

Seth

[Top]


Author: Daniel Berlinger

Date:11/21/2002

Permalink Icon

# 2621

RE: The "Value" of My RSD Approach...

I've folded your ideas in Seth, and have moved some elements around. This should make it possible for folks to write very simple api entries, or as detailed as someone deems necessary, using Seth's idea for settings elements.

The elements I've moved are the notes and docs and blogID. blogID has been moved as an optional attribute of api. It can also be a setting element. That's how I portrayed it in the "Conversant" api example (with apologies to Seth). Notes and docs are also optional this way as well.

I think this version is getting really close to solving most of the issues. let me know what you think.

I also agree that it's a good idea to have a suggested spot... thoughts are welcome of course.

[Top]


Author: Brent Simmons

Date:11/21/2002

Permalink Icon

# 2623

RE: The "Value" of My RSD Approach...

The only possible nit I'm seeing with the latest XML example on Daniel's page now is that in some cases blogID is an attribute of the API and other times it's in the settings section.

I'm thinking it should be in one place or the other, it shouldn't be allowed in two places.

Otherwise -- yes, it looks like it's very close to soup.

[Top]


Author: Seth Dillingham

Date:11/21/2002

Permalink Icon

# 2624

RE: The "Value" of My RSD Approach...

On 11/21/02, Brent Simmons said:

>The only possible nit I'm seeing with the latest XML example on 
>Daniel's page now is that in some cases blogID is an 
>attribute of the API and other times it's in the settings section.
>
>I'm thinking it should be in one place or the other, it shouldn't be
>allowed in two places.
>
>Otherwise -- yes, it looks like it's very close to soup.

The same goes for all of the attributes/elements: one or the other. No need for that kind of flexibility, it just makes things confusing. (He said something about allowing one of the URL's to be elements or attributes, but it should only be one or the other.)

Seth

[Top]


Author: Brent Simmons

Date:11/21/2002

Permalink Icon

# 2625

RE: The "Value" of My RSD Approach...

>The same goes for all of the attributes/elements: one or the other. No need for that kind of flexibility, it just makes things confusing.

Agreed, completely.

[Top]


Author: Daniel Berlinger

Date:11/21/2002

Permalink Icon

# 2627

RE: The "Value" of My RSD Approach...

Allrighty,

blogID is an attribute.

Should all the attributes be required? Maybe blogID should be optional? (That's not the way it currently shows in the example (http://archipelago.phrasewise.com/rsd)

Also, if there is an API name you'd like on the list, by all means drop me a note. I'll be getting a preliminary list posted before the end of the weekend.

d.

[Top]


Author: Daniel Berlinger

Date:11/21/2002

Permalink Icon

# 2628

RE: The "Value" of My RSD Approach...

Allrighty,

blogID is an attribute.

Should all the attributes be required? Maybe blogID should be optional? (That's not the way it currently shows in the example (http://archipelago.phrasewise.com/rsd)

Also, if there is an API name you'd like on the list, by all means drop me a note. I'll be getting a preliminary list posted before the end of the weekend.

d.

[Top]


Author: Daniel Berlinger

Date:11/21/2002

Permalink Icon

# 2629

RE: The "Value" of My RSD Approach...

Allrighty,

blogID is an attribute.

Should all the attributes be required? Maybe blogID should be optional? (That's not the way it currently shows in the example (http://archipelago.phrasewise.com/rsd)

Also, if there is an API name you'd like on the list, by all means drop me a note. I'll be getting a preliminary list posted before the end of the weekend.

d.

[Top]


Author: Seth Dillingham

Date:12/17/2002

Permalink Icon

# 2692

RSD Moving to 1.0

Daniel just sent out an email to inform interested parties that, tomorrow morning, RSD is moving to version 1.0. His proposal:

  • Fixes a bug in the declaration of RSD's default XML Name Space (it's been correct in the new Weblog plugin's RSD files all along, but I forgot to tell him about it).

  • Change the value of the api "name" attribute, from an actual name to a URL. I don't like this, and apparently Dave Winer doesn't either. (Daniel has apparently changed his mind on this one since Dave posted his comments.)

  • Change api's "rpcLink" attribute to, uh... something else. He hasn't decided yet between "location", "apiLink", "location", and "apiLocation".

It's surprising that Daniel is rushing to 1.0 so quickly (tomorrow morning?), since two of the three changes he wants to make are unclear, undecided, or both. Of course he wants to foster growth, "make it happen" more quickly, but RSD is already being adopted very quickly because it was so carefully considered in the first place. Less than one day from his announcement of the proposed changes to the actual release?

Can't let this end on a sour note, so I'll add that RSD is very cool. It's easy to support, flexible, and its existence is predicated on making software easier to use. If the spec goes GM a few days early, so what? That won't make it any less effective.

[Top]


Author: Jim Roepcke

Date:12/18/2002

Permalink Icon

# 2693

Re: RSD Moving to 1.0

On Tuesday, December 17, 2002, at 12:26 PM, Seth Dillingham wrote:

> Can't let this end on a sour note, so I'll add that RSD is very cool.
> It's easy to support, flexible, and its existence is predicated on
> making software easier to use. If the spec goes GM a few days early,
> so what? That won't make it any less effective.

In the grand scheme of things, what's a few days to get something done
right, or if you're that confident, taking the time to make
stakeholders comfortable? It's positive thinking to say it won't make
it less effective, but also wishful thinking. Things can get screwed
up, the devil is in the details. And everyone lives with the
consequences for a long time.

I've never understood the desire in some people to speed these things.
Perhaps it's the Christmas-rush, people get in a panicked state around
this time of year.

I hope RSD turns out well, because I think it's a great idea and I'm
very glad Daniel (and yourself) got it going.

Jim

[Top]


Author: Seth Dillingham

Date:12/18/2002

Permalink Icon

# 2694

RSD 1.0 in Conversant's Weblogs

RSD is now fully supported in both types of Conversant's weblogs: the "old ones" (which is all that's publicly available) and the new Weblog II pages.

Daniel announced 1.0 this morning, and the changes from 0.6 were extremely trivial. Macrobyte announced full support this afternoon.

All Conversant weblogs support RSD automatically, and the default templates include the RSD "link" tag in the header (and it's very easy to add it to custom templates, you can see it in the header for my site if you look at the source).

It's gratifying to see something I participated in (RSD) gain traction so quickly in the industry. Most of the weblog tools either support or have announced plans to support RSD. Pretty cool.

[Top]



<- Previous Thread:
Apple Events and Frontier

Next Thread: ->
Conversant Macro Glossary for BBEdit

Until August 31
My Amazon sales
benefit the PMC

Homepage Links

Apr 1 - Aug 31
Ad revenue
benefits the PMC


TruerWords
is Seth Dillingham's
personal web site.
Read'em and weep, baby.