Subject: [OAUTH-WG] Proposal: Develop Implementor's Guides for Major Use Cases

From: "Richer, Justin P." <[email-masked]>
Date: Tue, 13 Jul 2010 15:13:32 -0400

Brian's brought up the point that the new organization would cause an implementor to have to jump all around the spec to find all the parts needed. I propose that the working group work on a set of "implementor guides" that detail exactly what parts one needs to deal with all of the major use cases. These would cover both the client and server cases, and would be worded along the lines of "listen like this, accept these five arguments that do this, and return this". In this way, it would be closer to the -06-and-earlier "profiles". 

I can see value in this helping adoption. An implementor isn't going to care about elegant organization of thoughts if they can't figure out what parameters to listen for. A set of guides like this would give someone a direct, non-ambiguous way to go about building stuff. Case in point, in all my implementations of OAuth 1.0, I referred more to the connection diagrams than I ever did to the protocol spec.

But this of course does beg us to ask, shouldn't the spec itself fill this role? Or can it?

 -- Justin

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 13 Jul 2010 12:19:10 -0700

I think the spec should address this. I don't think it needs to go back to -06 format. There is a middle ground. 

Also, keep in mind that the current format is much easier for those implementing multiple flows or servers. 

The important part is to make the spec instructive, not to optimize linear reading. It's a spec and internal references are part of the deal.

EHL

On Jul 13, 2010, at 15:13, "Richer, Justin P." <[email-masked]> wrote:

> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth