intertwingly

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 complete implementations.  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.

As far as the black magic goes, here’s where having an existing implementation helps.  I can provide the equivalent building blocks in Ruby, and then verify in a unit test that the Ruby methods provide the same results as the Python functions.

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.