lj_dev: TypeKey API manual problems

the auroran sunset (

tithonus) wrote in

lj_dev,
@ 2006-10-08 06:25:00

TypeKey API manual problems
Not sure if this is a good place to put this, but I can see no obvious way of contacting sixapart on from their site, and I'm assuming there is a lot of cross-pollination between the two projects (LJ and TypeKey).

I've just finished writing a custom PHP implementation of TypeKey. I realise that this has been done before (e.g. Solar_Auth_TypeKey) - it just seemed to be the best way to learn how it all worked.

My final problems came as the result of two errors in the explanation of the 'sig' field in both versions of the TypeKey API manual on the sixapart website.

One error is just confusing, the other is catastrophic. Obviously many developers must have already spotted and corrected the errors (presumably by reading the source code to find what the API *really* is), because I have found implementations on the web which work correctly.

Here's what the manuals say:

The DSA signature of the string formed by concatenating the following values, separated by double-colons:

<email>::<name>::<nick>::<ts>::<site-token>

<site-token> is the parameter <t> that was passed to TypeKey. To give an example, if I was ``Napoleon Bonaparte'' <napoleon@france.fr> with a login name of 'napster', and I logged in from an app with TypeKey token hql3XGNq1fB1cSjlCZ3i at 2001-09-08 19:00:00 (or 1000000800 seconds from the epoch), sig would be the signature for this string:

napoleon@france.fr::Napolon Bonaparte::napster::1000000800::hql3XGNq1fB1cSjlCZ3i

The confusing error is in the example, which is in the form:-
<email>::<nick>::<name>::<ts>::<site-token>, rather than <email>::<name>::<nick>::<ts>::<site-token> as it should be.

The catastrophic error is that the signature is actually of the form:
<email>::<name>::<nick>::<ts>
ie without the <site-token> on the end!

Thus the example should read:
napoleon@france.fr::napster::Napolon Bonaparte::1000000800

(Should Napoleon be spelt correctly?!)

Obviously the manuals should be corrected ASAP. Hopefully someone here knows how to get that to happen, or knows who I should be telling... Or can really surprise me by explaining why these aren't actually errors! :-)

(Post a new comment)

anildash
2006-10-08 04:50 am UTC (link)

I'll try to track this down with the folks who know more about how TypeKey works, but I think the two links you have for our TypeKey docs go to the same place? How do they compare to the docs at http://www.sixapart.com/developers/typekey.html ?

Sorry this stuff is out of date... we've been talking about TypeKey becoming a better OpenID provider and then simplifying things so people can use OpenID for as much as possible, but that's still very early as well. Bug reports or amendments to the TypeKey wiki are very welcome.

(Reply to this)(Thread)

tithonus
2006-10-08 03:23 pm UTC (link)

That link gets me through to a third version of API documentation which contains all the errors mentioned above. Oops. :-/

Sorry this stuff is out of date...

Does that imply you are a responsible bod? (I haven't read lj_dev for a couple of years, so don't know who people are).

we've been talking about TypeKey becoming a better OpenID provider and then simplifying things so people can use OpenID for as much as possible, but that's still very early as well.

What amazes me is that TypeKey is obviously used successfully on thousands of sites. All these programmers must have worked out the correct API from somewhere (many like me from desparately try an "incorrect" version they are loosely cribbing). Yet in all that time, none of them have told SixApart; or alternatively, nobody at SixApart has found the time to change this presumably highly used bit of documentation.

The above is why I'm still suspicious that I'm missing something important and the documentation is in fact correct, even though it doesn't seem to work and 'my' version does seem to work! Maybe I should be a bit more confident.

Is OpenID another name from TypeKey, or some different similar system, or a general name, or something totally different? (I should just look it up!).

(Reply to this)(Parent)

	mendel 2006-10-08 04:52 am UTC (link)
	At the bottom of every page on Six Apart's website is a "Contact Us" link that goes here. Go there, click on "Typekey", paste in your thingy. (Reply to this)(Thread)

	vanbeast 2006-10-08 05:22 am UTC (link)
	this is approximately the third time in the last couple of weeks that someone (usually a technical person!) has complained that it's hard to contact sixapart... apparently you and I are the only ones who can see that link. (Reply to this)(Parent)

ruakh
2006-10-08 06:13 am UTC (link)

There's a mess of tiny links at the bottom of Six Apart pages, so it's not shocking that someone wouldn't notice the link, and would instead try to navigate through the site's normal interface by clicking on "Support." (Of course, it's easy to search the page for plausible text of a contact link, but that only helps if it occurs to you that the page you're at might link directly, but subtly, to the contact page.)

(Reply to this)(Parent)(Thread)

	pbristow 2006-10-09 01:41 am UTC (link)
	[NODS] The main problem here is a failure (on 6A's part) to think about the end user. (Reply to this)(Parent)(Thread)

	ruakh 2006-10-09 02:23 am UTC (link)
	Wow, harsh. Have you ever designed a complex user interface? It's not so easy. (Reply to this)(Parent)(Thread)

	pbristow 2006-10-09 08:22 am UTC (link)
	Yes I have, and I know it's not. However, it really doesn't help when you start out with a mental block on regarding who your target user is and what they're likely to know, and there's plenty of evidence lately of LJ developers having such blocks. That said, I probably shouldn't have joined in this thread while I was still PO'd with LJ about other stuff. =:o\ (Reply to this)(Parent)

	njyoder 2006-10-08 07:24 am UTC (link)
	Did you bother to read the page you're describing? It doesn't actually offer an option for reporting errors with their manual. If you're going to complain about people not reading things, it helps to read yourself before making that complaint. (Reply to this)(Parent)(Thread)

	pauamma 2006-10-08 07:36 am UTC (link)
	You could report it as a login problem. :-) (Reply to this)(Parent)(Thread)

	njyoder 2006-10-08 08:00 am UTC (link)
	You could, but that's not really what it was meant for. Reporting it as a website problem might actually be closer, since the manual is technically a part of the website. Regardless, they'll probably forward it to whoever it's actually supposed to go to. (Reply to this)(Parent)(Thread)

	tithonus 2006-10-08 03:51 pm UTC (link)
	I have now sent a short report pointing them toward this page (and the extra site usability problems detailed in the comments) to both or your suggestions. As you say, somebody should know what to do with it! :-) (Reply to this)(Parent)

	christine 2006-10-08 11:42 am UTC (link)
	Aside from the "website feedback" (which seems like a plausible option to me), they also have a "general questions" option, which would suit your purpose just as well. I'm pretty sure either of those are better than coming to LJ_dev with a typekey issue. (Reply to this)(Parent)(Thread)

tithonus
2006-10-08 03:33 pm UTC (link)

The general questions one says "Totally at a Loss (and not about technical issues)", which suggests they wouldn't want it sent there. I think the "website feedback" or the typekey area's "login problems" ones are the most likely, but neither are ideal.

As you say, they will probably forward it on the appropriate people, as I imagine it will be forwarded on from here also. Given the difficulties finding that contact page, let alone working out where to send it from that page, and that I know various of the higher up techs at SixApart at least used to read lj_dev regularly, I don't think posting here was a particularly bad option.

(Reply to this)(Parent)(Thread)

	pbristow 2006-10-09 01:47 am UTC (link)
	One would HOPE it would be forwarded on, but that seems not to be general practice these days in commercial organisations. "You have sent your communication to the wrong department. Please go to this (totally differently formatted) page and re-enter your (not very obviously compatible with required format) query" seems to be the mode du jour.... =:o/ (Reply to this)(Parent)(Thread)

tithonus
2006-10-09 01:58 pm UTC (link)

My impression when I was last reading this community, admittedly a year or more ago, that Brad and co. do watch and deal with problems when they come up.

As for the companies that try to force the customers to do their work for them, they will in the end lose out. I doubt I am unusual in not bothering when they suggest such things, just as I don't bother when they try to make me register to read something or to tell them something (hence I didn't use the SixApart support page that I did find). Such behaviour will result in the users/customers becoming more and more reluctant to help, and thus the service further deteriorating. However, my impression is that LJ is no where near that far gone.

(Reply to this)(Parent)

mendel
2006-10-08 05:14 pm UTC (link)

Of course I did. It's an obvious way of contacting Six Apart on their site. Given the options "Send someone responsible for TypeKey a message via a form with a TypeKey logo on it" and "Post to a LiveJournal community", guess which one works better!

I mean maybe you're right and the original poster went to that page and came to the same conclusion you did, but I think he actually didn't find it.

(Reply to this)(Parent)

	Reporting Errors byrnereese 2006-10-09 06:01 pm UTC (link)
	You can always leave a comment or "note" on the manual's page: http://www.sixapart.com/developers/product_documentation/typekey/typekey_authentication_protoco.html That would be a logical place to log errors wouldn't ya think? :) (Reply to this)(Parent)(Thread)

	Re: Reporting Errors tithonus 2006-10-10 12:03 pm UTC (link)
	ooo, a third (fourth?) version of that page! this time will a helpful form. encroyable! well spotted, or something. :-) (Reply to this)(Parent)

tithonus
2006-10-08 03:26 pm UTC (link)

Not quite every page: neither of the two I linked to have it.

As someone else has said, it is not easy to find unless you know it is there - something else for the websprites to work on I suppose. Thank you for finding it and pointing the way.

Also as others have said, the contact page's catagories are not very transparent. I'll try one sort of at random. You'd think that a big open-source operation would have a "bug report" address, or something similar. Perhaps they do and I'm missing that too. :-/

(Reply to this)(Parent)(Thread)

	mendel 2006-10-08 05:14 pm UTC (link)
	I didn't know it was there. I went to www.sixapart.com and searched the page for the word "contact". (Reply to this)(Parent)(Thread)

	tithonus 2006-10-08 09:33 pm UTC (link)
	! Now that's what I call a user-friendly interface! Little wonder people give up trying to find the contact page so easily. :-/ I've mentioned that also in my queries via the page you kindly found. Thank you. (Reply to this)(Parent)

pbristow
2006-10-09 01:53 am UTC (link)

...Which of course SHOULD NOT BE NECESSARY.

Specifically, it should not be necessary to employ a non-default feature of (any typical browser) simply to find the means to contact the owners/maintainers of the site one is currently browsing. Any honest and clueful corporation would have the means of contacting them *HIGHLIGHTED*; not hidden so carefully that it requires search facilities to locate it!

(Reply to this)(Parent)(Thread)

mendel
2006-10-09 02:32 am UTC (link)

Dude, you're yelling at me in a Livejournal comment because some guy couldn't find out how to contact Six Apart and I showed him how I found it. I don't want

lj_dev to become a talk-to-6A-about-anything dropbox so I suggested that the poster could stand to look harder instead of posting off-topic here and hoping for the best. If you're that angry about their webpage, use the contact form and tell them. I sure can't fix it.

(Reply to this)(Parent)(Thread)

	pbristow 2006-10-09 08:16 am UTC (link)
	Sorry, but it seemed to me you were not getting the point and/or trying to dismiss it. If that's not the case then I apologise. My frustration was mainly with LJ/6A, however (following hot on the heels of another "oops, we forgot about the users" debacle), and all yelling should be interpreted as directed at them - after all, they are (hopefully) reading this comm. (Reply to this)(Parent)

Mini Sitemap:

Username:		Create an Account Forgot your login? Login w/ OpenID
Password:
	Remember Me
	English • Español • Deutsch • Русский…