Re: [OAUTH-WG] Looking for a compromise on signatures and other open issues

[Eran Hammer-Lahav <[e-mail]>]

> -----Original Message-----
> From: Dick Hardt [mailto:[e-mail]]
> Sent: Tuesday, September 28, 2010 5:09 PM

> I am mildly concerned that breaking the spec into multiple parts makes it
> harder for the spec reader to understand what is going on. Where does a
> complete example of getting and using a token? Imagine how confusing
> HTTP would be if the request and response were in separate specs.

You mean like break the HTTP specification into, say, 7 parts? Maybe something like this:

1: URIs, Connections, and Message Parsing
2: Message Semantics
3: Message Payload and Content Negotiation
4: Conditional Requests
5: Range Requests and Partial Responses
6: Caching
7: Authentication

This is exactly what the original HTTP authors are doing these days [1]. You should have probably chose another example to make your point :-).

Joking aside, I don't buy this argument for two reasons. First, most developer are not going to read the actual specification - they will read API documentations, books, and tutorials. Very few people actually read RFC 2616 in whole (most just use it as a reference for status codes). Second, you are exaggerating the complexity of following a link to another part.

Would it be better to have everything in one document? Sure! But is it worth delaying this work by another year or so? That's the point of this compromise. It gives everyone the technical details they care about, treats competing views equally, at the small cost of having to read one more document (but same number of pages) if you only care about bearer tokens. That's the compromise.

I am confident that I can write easy to follow prose that will explain that this specification shows how to obtain a token, while other specifications show how to use it (and discuss the specific properties of different token types).
 
I believe my detailed proposal addresses all the points raised in your feedback.

EHL

[1] http://tools.ietf.org/wg/httpbis/