oltu-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Simone Tripodi <simone.trip...@gmail.com>
Subject Re: APIs
Date Tue, 15 Jun 2010 20:14:44 GMT
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 ...

maybe everybody agrees that this is not so nice to have in our code :P

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?
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
View raw message