oltu-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tommaso Teofili <tommaso.teof...@gmail.com>
Subject Re: APIs
Date Wed, 16 Jun 2010 05:52:23 GMT
Hi guys,
from the design point of view I'd strongly prefer having annotations over a
Map.
My reasons for that are the following:

   1. Code cleanness and readability
   2. Having separate Message subclasses defining their parameters it helps
   and guides towards defining a strict specification API (i.e.: a messages of
   type DummyMessage need to have 3 parameters: paramA, paramB and paramC while
   a UselessMessage has only paramA and paramC)
   3. Annotations, as stated by Simone, let you define some more logic
   (required parameters, default values, etc...)
   4. Debugging maps it's annoying

I undersand your points Pid, it's only about two different approaches, I
think your one with Map is guided by the "keep things simple" rule.
I like discussions about design which let us talk, know and learn from one
another.
Cheers,
Tommaso

2010/6/15 Pid <pid@pidster.com>

> On 15/06/2010 21:14, Simone Tripodi wrote:
> > Nice to see we've gone deeply in the loop :)
> > Map is IMHO too generic, even if could help reducing the complexity
> > because of the parameters names, it doesn't allow adding metadata
> > annotations, so we would move the maintenance from the POJO to the
> > algorithm, and forced to hard-code logic discriminating parameters.
> > Immagine the snippet below (in meta language):
> >
> > if ("oauth_signature".equals(parameter)) {
> >     // do something
> > } else if ("oauth_version".equals(parameter)) {
> >     // do something
> > } else ...
>
> I don't see the need for that anywhere?
>
> > maybe everybody agrees that this is not so nice to have in our code :P
>
> Me either.
>
> > Generally speaking, I'd continue prefer maintain POJOs instead the
> > algorithm, since POJOs are just types declaration and don't contain
> > any logic.
>
> > More thoughts?
>
> I agree.  I just don't see the need to annotate fields, which you have
> to list, then sort alphabetically (for correct concatenation), before
> reflectively extracting their values.
>
> Maybe I misunderstood; you were only referring to the known OAuth
> parameters rather than the possible additional parameters that a
> Consumer might need, that have to be supplied to the Provider during auth?
>
>
> p
>
> > Simo
> >
> > http://people.apache.org/~simonetripodi/
> >
> >
> >
> > On Tue, Jun 15, 2010 at 9:46 PM, Pid <pidster@apache.org> wrote:
> >> On 15/06/2010 20:07, Simone Tripodi wrote:
> >>> Hi Pid,
> >>> that's curious and funny at the same time, that's exactly what I've
> >>> always avoided to do :) And don't worry, even if with totally
> >>> different vision, we're here to work together for the same purpose,
> >>> that's why we partecipate in a community, otherwise everybody could
> >>> work alone, no? :P
> >>>
> >>> In the case of the Message, the reason why I thought so is that
> >>> annotations contain not only the name parameter name, but also some
> >>> logic hints that avoid us hard-coding logic in the client algorithm,
> >>> like exclude parameters during the signature, the optional fields and
> >>> so on.
> >>> It helps to maintains the code more flexible - if new parameters have
> >>> to be added, just extend the POJO and add new annotation, logic has
> >>> not to be changed - and consequently more maintainable.
> >>
> >> I understand.  I think that perhaps a Map might be more simple though -
> >> you wouldn't need to recompile to handle new parameters?
> >>
> >>
> >> p
> >>
> >>> http://people.apache.org/~simonetripodi/
> >>>
> >>>
> >>>
> >>> On Tue, Jun 15, 2010 at 7:54 PM, Pid <pidster@apache.org> wrote:
> >>>> On 15/06/2010 16:14, Simone Tripodi wrote:
> >>>>> Hi Simo,
> >>>>> absolutely right, let's find a better way to describe how I started
> >>>>> designing the signature APIs...
> >>>>>
> >>>>> First of all: use cases show us that there are symmetric algorithms
> >>>>> (PLAINTEXT, HMAC_SHA) and asymmetric algorithms (RSA_SHA1), so the
> >>>>> design should be able to be adaptable for both cases. I thought
that
> a
> >>>>> symmetric algorithm is a special case of an asymmetric algorithm,
so
> >>>>> let's consider having a SigningKey and a VerifyingKey interfaces,
in
> >>>>> the case of a symmetric algorithm, the key implementation have to
> >>>>> implement both interfaces.
> >>>>>
> >>>>> So, let's define the SignatureMethodAlgorithm - I hope the name
is
> >>>>> semful!!! That's the interface definition
> >>>>>
> >>>>> public interface SignatureMethodAlgorithm<S extends SigningKey,
V
> >>>>> extends VerifyingKey>
> >>>>>
> >>>>> where defined the the method to calculate the signature (throws
> >>>>> SignatureException if any error occurs):
> >>>>>
> >>>>>     String calculate(S signingKey,
> >>>>>             String secretCredential,
> >>>>>             Service service,
> >>>>>             RequestMessage message,
> >>>>>             Parameter... parameters) throws SignatureException;
> >>>>>
> >>>>> and the one to verify the signature:
> >>>>>
> >>>>> boolean verify(String signature,
> >>>>>             V verifyingKey,
> >>>>>             String secretCredential,
> >>>>>             Service service,
> >>>>>             RequestMessage message,
> >>>>>             Parameter... parameters) throws SignatureException;
> >>>>>
> >>>>> An abstract implementation, AbstractSignatureMethodAlgorithm,
> contains
> >>>>> common signature calculation stuff, like the base string creation.
> >>>>> Any SignatureMethodAlgorithm implementation is annotated by a
> >>>>> @SignatureMethod annotation to mark the oauth algorithm identifier,
> >>>>> ie:
> >>>>>
> >>>>> @SignatureMethod("HMAC-SHA1")
> >>>>> public final class HmacSha1MethodAlgorithm extends
> >>>>> AbstractMethodAlgorithm<HmacSha1Key, HmacSha1Key> {
> >>>>> ...
> >>>>> }
> >>>>>
> >>>>> Let's now make clear what hell Service, RequestMessage and Parameter
> are :)
> >>>>>
> >>>>>
> >>>>> Service is the pair (URL, HttpMethod) that describes the service
has
> >>>>> to be invoked. HttpMethod is an enumeration of all admitted http
> >>>>> method:
> >>>>>     HEAD,
> >>>>>     POST,
> >>>>>     PUT,
> >>>>>     GET,
> >>>>>     DELETE,
> >>>>>     OPTIONS,
> >>>>>     TRACE,
> >>>>>     CONNECT
> >>>>>
> >>>>>
> >>>>> RequestMessage is a POJO that contains the OAuth parameters like
> >>>>> version, nonce, timestamp, ... it is extended by the
> >>>>> TokenRequestMessage that differs from the previous one because
> >>>>> contains the token field.
> >>>>> Every RequestMessage field is annotated by @OAuthParameter
> annotation,
> >>>>> to mark if the field:
> >>>>> - is optional (false by default)
> >>>>> - has to be included in the parameter list to calculate the signature
> >>>>> (true by default)
> >>>>> - moreover contains the oauth parameter name
> >>>>>
> >>>>> a sample can be found on the signature field:
> >>>>>
> >>>>> @OAuthParameter(
> >>>>>             name = "oauth_signature",
> >>>>>             includeInSignature = false
> >>>>>     )
> >>>>>     private String signature;
> >>>>>
> >>>>> That's all in therms of design, there are few little tricks on the
> >>>>> implementation side (java introspection rocks) but IMHO is small
and
> >>>>> intuitive.
> >>>>>
> >>>>> What do you think about it? Thoughts? Any feedback is more than
> welcome!!!!
> >>>>
> >>>> I hope you'll forgive me for saying so, but I think it's quite
> >>>> complicated.  Annotations are nice, but seem like overkill for this
> >>>> use-case.
> >>>>
> >>>> If the POJO contains all of the necessary items as named fields, why
> not
> >>>> just concatenate and encode them in the correct order?
> >>>>
> >>>>
> >>>> p
> >>>>
> >>>>
> >>>> (Sorry Simo!)
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>> All the best, have a nice reading :P
> >>>>> Simo
> >>>>>
> >>>>> http://people.apache.org/~simonetripodi/
> >>>>>
> >>>>>
> >>>>>
> >>>>> On Tue, Jun 15, 2010 at 4:17 PM, Simone Gianni <simoneg@apache.org>
> wrote:
> >>>>>> Hi Simo,
> >>>>>> obviously current SVN *is* the starting point.
> >>>>>>
> >>>>>> Let's see how to continue on that line, if there are other
> proposals, if
> >>>>>> some of our other existing code bases approach in a different
way,
> or if
> >>>>>> someone foresees some other kind of problems in integrating
the
> current API
> >>>>>> with their app.
> >>>>>>
> >>>>>> Simone
> >>>>>>
> >>>>>> 2010/6/15 Simone Tripodi <simone.tripodi@gmail.com>
> >>>>>>
> >>>>>>> Hi Simo,
> >>>>>>> currently in the current svn Amber repo there is the signature
> (with
> >>>>>>> implementation) and part of consumer APIs I wrote time ago
for the
> >>>>>>> Lab.
> >>>>>>> They are still valid IMHO and part of my proposal, parts
of code
> could
> >>>>>>> be extracted from there.
> >>>>>>>
> >>>>>>> Feel free to ask questions if some parts are not clear.
> >>>>>>> All the best,
> >>>>>>> Simo
> >>>>>>>
> >>>>>>> http://people.apache.org/~simonetripodi/<
> http://people.apache.org/%7Esimonetripodi/>
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> On Tue, Jun 15, 2010 at 2:21 PM, Simone Gianni <simoneg@apache.org>
> wrote:
> >>>>>>>> Hi all,
> >>>>>>>> so, one part of our roadmap are APIs.
> >>>>>>>>
> >>>>>>>> Each of us has his own idea of how an API should be,
in general,
> and many
> >>>>>>> of
> >>>>>>>> us already have an idea (or even code) on how an OAuth
API should
> be :)
> >>>>>>>>
> >>>>>>>> There is no "absolute way" to determine if an API is
better or
> worse than
> >>>>>>>> another. It mostly depends on use cases.
> >>>>>>>>
> >>>>>>>> Amber will (as many other systems) interact with :
> >>>>>>>> - external applications/frameworks, using Amber to integrate
oauth
> >>>>>>>> - internal extensions, providing for example different
token
> storages or
> >>>>>>>> interation different backends
> >>>>>>>> - modules of Amber itself
> >>>>>>>>
> >>>>>>>> I think it would be better to focus on the first API
now : which
> use
> >>>>>>> cases
> >>>>>>>> do we plan? How do you imagine the code of a web framework
using
> Amber
> >>>>>>> look
> >>>>>>>> like?
> >>>>>>>>
> >>>>>>>> If there are very different cases there is space for
more than one
> API,
> >>>>>>> for
> >>>>>>>> example a low level one and high level Fa├žade. Since
our goal is
> to unify
> >>>>>>>> different (often existing) pieces and ease the path
of adoption on
> >>>>>>> projects
> >>>>>>>> that were planning to integrate OAuth, we'll need a
bit of
> flexibility.
> >>>>>>>>
> >>>>>>>> Cast your code sample ideas :) People in projects that
already use
> their
> >>>>>>> own
> >>>>>>>> implementation of OAuth can easily post real code.
> >>>>>>>>
> >>>>>>>> Simone
> >>>>>>>>
> >>>>>>>
> >>>>>>
> >>>>
> >>>>
> >>>>
> >>
> >>
> >>
>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message