Jon
Udell: I learn poorly from API documentation, and rely
almost exclusively on examples.
Me too.
Judging by the
mailing list,
it looks like the was one, and possibly two, false starts towards
building an OpenID implementation
on Rails. I will say that the
API documentation has
improved since I
last
looked, but IMHO it still is significantly lacking in the way
of examples.
What is more significant is the release of
completeimplementations.
However, even that doesn’t help people like me to understand
what is going on anywhere near as much as test cases would.
For example, look at test_associate_cleartext in
OpenidControllerTest. It says that if I post to a given
URI specifying ‘openid.mode=associate’, I should get
back a mac_key and an assoc_handle. Furthermore, if I could
reach into the database on the server and search the
‘assocs’ table for row containing the specified
assoc_handle, I would get a secret that matches the mac_key (after
undoing the base64’ing) that was provided on the
response.
That’s simple enough that I could pick it up from the API
documentation. But lets look at the next test:
test_associate_dh_sha1. If I create a key exchange, and pass
it on the request, I can get back an enc_mac_key and a
dh_server_public key, both of which are unique to this
request. I can use that information, coupled with my original
key information, in a specific way to retrieve back the secret
that’s in the server’s assocs table. A bit harder
to understand, particularly as the mathematics essentially is black
magic, but still something that I find much easier to grok than the
API documentation which leaves much of this unsaid.
I now need to build up to the point where I have capture
scenarios what happens when an authenticated user first encounters
a new site. Sure, the specific redirect will be application
specific, but being able to express such examples in concrete terms
is an essential step required for people like Jon and I to
understand how the pieces fit together.
Like apparently everybody else, I am looking into this as much
to learn Rails as I am OpenID. Differences from the other
approaches that I have seen: I am not looking to build a framework,
but an application. I’m not looking to create an
abstract storage interface, I will be using
ActiveRecord with a
concrete
schema. Instead of building logic that can be called by
the application code that provides the views, I am implementing a
controller that will make use of templates that can be
tailored.
Finally, there will be plenty of test cases.
Me three. I always go through a period of frustration learning a new library when all I have to go on is API documentation and maybe a few paltry examples. What I really want to know are the patterns of the library, not the atomic details. The trend toward recipe-style books is a good one.
Can you drop me an email explaining on this post a bit in terms of what all you are looking for? While, as you said, the docs have gotten better we know they still have places to grow as well. I’ll pass it along to Brad and hopefully we can make the site more useful.
David, I’ll join you, Brad, and others on the mailing list shortly. My problem is that I almost — but not quite — know enough to ask intelligent questions.
One thing that would definitely be appreciated is wiretraces. Suppose I had a new laptop (i.e., with no cookies), a pre-existing sctuff account, and I wanted to post a comment to your LiveJournal - exactly what traffic would we see?
Sure, most of the strings in the wiretraces would be opaque base64 data, but it still would make it a lot easier for me to visualize what is going on.
For Java, sites like www.javaalmanac.com are pretty useful. If there’s a core Java API which I’ve got to use for the first time, it’s often a useful place to go to get a code snippet to get you up and running.
Sam, I’m not sure there are any HOWTOs on building a Rails generator. I’d start with Tobi’s LoginGenerator as the canonical example.
Seems like code reuse is currently getting shorted by the community (mechanisms like generators and components exist, but are under documented, and there certainly isn’t a booming pool to draw from)
We’re dealing with those issues now. We just added a new plugin “architecture” in the SVN version that’ll make it easier and more standardized to distribute stuff like acts_as_taggable.
We’re going to overhaul components too. And then, finally, we’re going to make a place for the sharing and production of all this.
I’m mid-way through porting our Python-OpenID library to Ruby. It shares the same interface as the Python and PHP libraries, and will be available for download and review next week. Also, a Rails generator will follow!
Lately i’ve been seeing a lot of buzz about OpenID, and i’ve got to admit, it’s a darn appealing idea, it’s just that i don’t see it as quite the utopia that others seem to. i get that OpenID is basically an identification service. What it says is...