You are viewing a plain text version of this content. The canonical link for it is here.
Posted to architecture@airavata.apache.org by Saminda Wijeratne <sa...@gmail.com> on 2014/01/31 05:54:35 UTC

Documenting Airavata API usage patterns

I'm thinking of the reasons why we are having trouble getting a proper API
to work smoothly is that,


   1. We are trying too hard to generalize when its probably not possible
   to do
   2. When we keep trying to see the big picture we miss the little things
   in the gateways that makes the usage of the API easy or hard for the
   developer.

eg: Not all gateways look at "Experiment Launch" use case as passing an
application name and its input to launch the experiment. (I think we've
came across many variations for this use case)

   - the inputs could be in different form (could be actual files) or just
   optional
   - application name could be just a reference to a parameter of a global
   application
   - part of the launch process may have runtime dependencies which gateway
   requires to participate
   - the gateway might want more control over the launch configurations at
   runtime.
   - ...

I think devs see it as a mismatch of the API for their gateway which
discourages the effort to use the API.

IMO part of our Thrift API effort should be to document these with the
solutions similar to Java Patterns.

In short, instead of trying to come up with a general API to make everyone
happy we provide solution patterns for a gateway use case which will have
multiple variations. (solution pattern would be use of the API + supporting
code which handles the variation)

wdyt?


Regards,

Saminda

RE: Documenting Airavata API usage patterns

Posted by "Miller, Mark" <mm...@sdsc.edu>.
Thanks Suresh, just let me know if I get too annoying...

-----Original Message-----
From: Suresh Marru [mailto:smarru@apache.org] 
Sent: Friday, January 31, 2014 11:59 AM
To: architecture@airavata.apache.org
Subject: Re: Documenting Airavata API usage patterns

Great points Mark and glad to see you every one's participation in these vital usability discussions. 

Suresh

On Jan 31, 2014, at 10:54 AM, Miller, Mark <mm...@sdsc.edu> wrote:

> Although I am non-technical, I would just like to say that (IMO) the 
> issues Saminda is raising here and our ability to finesse them as a group will be the single most important determinants of SciGap success or failure as a project and a software package.
> 
> -----Original Message-----
> From: Saminda Wijeratne [mailto:samindaw@gmail.com]
> Sent: Thursday, January 30, 2014 11:35 PM
> To: architecture
> Subject: Re: Documenting Airavata API usage patterns
> 
> I agree with your argument on identifying the focus groups and their needs and figuring out how to solve their problems. Figuring out a simple API is indeed important. My concern was more towards the next step. How to present our solution to the users. Having a well-defined API covering the required functionalities not necessarily can be made simple enough to be understood or doesn't explain most of the time how to arrive at a point where they can be used. For instance designing a function to retrieve experiment data requires us to understand atleast the level of granularity of the data expected, filtrations to be considered and the frequency of invocations.
> 
> On the few gateways I've worked so far (ParamChem, Ultrascan and
> CIPRES/NSG) I didn't see the direct usage of the current API. While in each case API showed alot of strength in certain areas where it made developer life really easy, most of the time they had to go through a few hops to actually to reach the use of API (and most of the time this is with our help). These hops are not always obvious and time it takes to figuring them out could be the difference between giving up or making a commitment to learn Airavata API nooks and corners. My point is that we can reduce this time by documenting what we already know on different variations of the same use case.
> 
> My recent experience on CIPRES + Airavata integration is a good example why I'm proposing this. CIPRES has a different pluggable framework of handling jobs and their data compared to Airavata. It took me a while to understand how Airavata can be plugged in to CIPRES even with my knowledge of Airavata and (limited though) CIPRES. Eventhough it wouldn't be an ideal way of integrating Airavata to CIPRES (one too many levels of abstractions) the resultant implementation is infact simple enough to understand to a gateway dev. But the fact is I had to spend alot of time getting to that solution.
> It was the same case with the ParamChem integration (although it took less time).
> 
> 
> On Thu, Jan 30, 2014 at 10:18 PM, Eran Chinthaka Withana < eran.chinthaka@gmail.com> wrote:
> 
>> Hi Saminda,
>> 
>> There are two major points we need to address to answer your question.
>> 
>> 1. who are we trying to cater and what they want 2. once we know what 
>> we want from #1 above how do we achieve it
>> 
>> #1: We can either make it easy for the scientists who use the gateway 
>> or make it easy for the developer, i.e. you. I think one of the major 
>> selling points for science gateways like Airavata is that it will 
>> make the life of a non-computer scientist easy by abstracting away 
>> the complexities of gateways. A common example we used to mention 
>> when we were in IU is that Sun Kim (a bio scientist in IU) should 
>> better spend his time trying to improve his algorithms than trying to 
>> tackle with WS-GRAM. Also, he should not worry too much when he 
>> decide to run an application in BigRed (if its still there :) ) vs 
>> NCSA vs Prof. Fox's windows HPC cluster. It should ideally be just a 
>> matter of flipping a switch in the API (but yes there will be some 
>> pre-preparation, like installing apps, before doing this). I think we 
>> should give priority to make it easy for the clients. So, if we agree 
>> on this with the conclusion that the scientists, i.e. Airavata 
>> clients are hidden from the underlying job submission mechanisms then we can tackle #2.
>> 
>> #2: When I was working with Sigiri (in my previous life) I had the 
>> same problem. I had two main methods to accomplish that.
>> 1. I looked into solutions like JSDL (
>> http://en.wikipedia.org/wiki/Job_Submission_Description_Language)
>> which had already come up with an abstraction. But this was kind of 
>> biased towards Grids.
>> 2. I looked into some of the existing gateways to define a generic 
>> API
>> 
>> At the end, I ended up defining a generic API from what I learnt from 
>> both methods but making sure the client API is simple. The API 1.
>> simple enough to submit simple jobs that are covering about 80% of 
>> the use cases (including parametric sweeps) 2. extensible enough to 
>> cover the corner cases which amounted to about 20% of the use cases
>> 
>> Within the implementations of each gateway, I had Adapters for each 
>> gateway and were picked based on what clients need. I can go into 
>> details if needed (and I need to go back to code) but this is something worth considering.
>> 
>> BTW, I understand the fact that the Airavata thrift API may be "hidden"
>> underneath XBaya but I'm sure there will be usecases where some 
>> scientists (and their poor grad students) wanting to launch workflows 
>> programmatically using thrift API.
>> 
>> Thanks,
>> Eran Chinthaka Withana
>> 
>> 
>> On Thu, Jan 30, 2014 at 8:54 PM, Saminda Wijeratne 
>> <samindaw@gmail.com
>>> wrote:
>> 
>>> I'm thinking of the reasons why we are having trouble getting a 
>>> proper
>> API
>>> to work smoothly is that,
>>> 
>>> 
>>>   1. We are trying too hard to generalize when its probably not possible
>>>   to do
>>>   2. When we keep trying to see the big picture we miss the little
>> things
>>>   in the gateways that makes the usage of the API easy or hard for the
>>>   developer.
>>> 
>>> eg: Not all gateways look at "Experiment Launch" use case as passing 
>>> an application name and its input to launch the experiment. (I think 
>>> we've came across many variations for this use case)
>>> 
>>>   - the inputs could be in different form (could be actual files) or
>> just
>>>   optional
>>>   - application name could be just a reference to a parameter of a
>> global
>>>   application
>>>   - part of the launch process may have runtime dependencies which
>> gateway
>>>   requires to participate
>>>   - the gateway might want more control over the launch 
>>> configurations
>> at
>>>   runtime.
>>>   - ...
>>> 
>>> I think devs see it as a mismatch of the API for their gateway which 
>>> discourages the effort to use the API.
>>> 
>>> IMO part of our Thrift API effort should be to document these with 
>>> the solutions similar to Java Patterns.
>>> 
>>> In short, instead of trying to come up with a general API to make
>> everyone
>>> happy we provide solution patterns for a gateway use case which will 
>>> have multiple variations. (solution pattern would be use of the API
>>> +
>> supporting
>>> code which handles the variation)
>>> 
>>> wdyt?
>>> 
>>> 
>>> Regards,
>>> 
>>> Saminda
>>> 
>> 


Re: Documenting Airavata API usage patterns

Posted by Suresh Marru <sm...@apache.org>.
Great points Mark and glad to see you every one’s participation in these vital usability discussions. 

Suresh

On Jan 31, 2014, at 10:54 AM, Miller, Mark <mm...@sdsc.edu> wrote:

> Although I am non-technical, I would just like to say that (IMO) the issues Saminda is raising here and our ability to finesse them as a group 
> will be the single most important determinants of SciGap success or failure as a project and a software package.
> 
> -----Original Message-----
> From: Saminda Wijeratne [mailto:samindaw@gmail.com] 
> Sent: Thursday, January 30, 2014 11:35 PM
> To: architecture
> Subject: Re: Documenting Airavata API usage patterns
> 
> I agree with your argument on identifying the focus groups and their needs and figuring out how to solve their problems. Figuring out a simple API is indeed important. My concern was more towards the next step. How to present our solution to the users. Having a well-defined API covering the required functionalities not necessarily can be made simple enough to be understood or doesn't explain most of the time how to arrive at a point where they can be used. For instance designing a function to retrieve experiment data requires us to understand atleast the level of granularity of the data expected, filtrations to be considered and the frequency of invocations.
> 
> On the few gateways I've worked so far (ParamChem, Ultrascan and
> CIPRES/NSG) I didn't see the direct usage of the current API. While in each case API showed alot of strength in certain areas where it made developer life really easy, most of the time they had to go through a few hops to actually to reach the use of API (and most of the time this is with our help). These hops are not always obvious and time it takes to figuring them out could be the difference between giving up or making a commitment to learn Airavata API nooks and corners. My point is that we can reduce this time by documenting what we already know on different variations of the same use case.
> 
> My recent experience on CIPRES + Airavata integration is a good example why I'm proposing this. CIPRES has a different pluggable framework of handling jobs and their data compared to Airavata. It took me a while to understand how Airavata can be plugged in to CIPRES even with my knowledge of Airavata and (limited though) CIPRES. Eventhough it wouldn't be an ideal way of integrating Airavata to CIPRES (one too many levels of abstractions) the resultant implementation is infact simple enough to understand to a gateway dev. But the fact is I had to spend alot of time getting to that solution.
> It was the same case with the ParamChem integration (although it took less time).
> 
> 
> On Thu, Jan 30, 2014 at 10:18 PM, Eran Chinthaka Withana < eran.chinthaka@gmail.com> wrote:
> 
>> Hi Saminda,
>> 
>> There are two major points we need to address to answer your question.
>> 
>> 1. who are we trying to cater and what they want 2. once we know what 
>> we want from #1 above how do we achieve it
>> 
>> #1: We can either make it easy for the scientists who use the gateway 
>> or make it easy for the developer, i.e. you. I think one of the major 
>> selling points for science gateways like Airavata is that it will make 
>> the life of a non-computer scientist easy by abstracting away the 
>> complexities of gateways. A common example we used to mention when we 
>> were in IU is that Sun Kim (a bio scientist in IU) should better spend 
>> his time trying to improve his algorithms than trying to tackle with 
>> WS-GRAM. Also, he should not worry too much when he decide to run an 
>> application in BigRed (if its still there :) ) vs NCSA vs Prof. Fox's 
>> windows HPC cluster. It should ideally be just a matter of flipping a 
>> switch in the API (but yes there will be some pre-preparation, like 
>> installing apps, before doing this). I think we should give priority 
>> to make it easy for the clients. So, if we agree on this with the 
>> conclusion that the scientists, i.e. Airavata clients are hidden from 
>> the underlying job submission mechanisms then we can tackle #2.
>> 
>> #2: When I was working with Sigiri (in my previous life) I had the 
>> same problem. I had two main methods to accomplish that.
>> 1. I looked into solutions like JSDL (
>> http://en.wikipedia.org/wiki/Job_Submission_Description_Language) 
>> which had already come up with an abstraction. But this was kind of 
>> biased towards Grids.
>> 2. I looked into some of the existing gateways to define a generic API
>> 
>> At the end, I ended up defining a generic API from what I learnt from 
>> both methods but making sure the client API is simple. The API 1. 
>> simple enough to submit simple jobs that are covering about 80% of the 
>> use cases (including parametric sweeps) 2. extensible enough to cover 
>> the corner cases which amounted to about 20% of the use cases
>> 
>> Within the implementations of each gateway, I had Adapters for each 
>> gateway and were picked based on what clients need. I can go into 
>> details if needed (and I need to go back to code) but this is something worth considering.
>> 
>> BTW, I understand the fact that the Airavata thrift API may be "hidden"
>> underneath XBaya but I'm sure there will be usecases where some 
>> scientists (and their poor grad students) wanting to launch workflows 
>> programmatically using thrift API.
>> 
>> Thanks,
>> Eran Chinthaka Withana
>> 
>> 
>> On Thu, Jan 30, 2014 at 8:54 PM, Saminda Wijeratne <samindaw@gmail.com
>>> wrote:
>> 
>>> I'm thinking of the reasons why we are having trouble getting a 
>>> proper
>> API
>>> to work smoothly is that,
>>> 
>>> 
>>>   1. We are trying too hard to generalize when its probably not possible
>>>   to do
>>>   2. When we keep trying to see the big picture we miss the little
>> things
>>>   in the gateways that makes the usage of the API easy or hard for the
>>>   developer.
>>> 
>>> eg: Not all gateways look at "Experiment Launch" use case as passing 
>>> an application name and its input to launch the experiment. (I think 
>>> we've came across many variations for this use case)
>>> 
>>>   - the inputs could be in different form (could be actual files) 
>>> or
>> just
>>>   optional
>>>   - application name could be just a reference to a parameter of a
>> global
>>>   application
>>>   - part of the launch process may have runtime dependencies which
>> gateway
>>>   requires to participate
>>>   - the gateway might want more control over the launch 
>>> configurations
>> at
>>>   runtime.
>>>   - ...
>>> 
>>> I think devs see it as a mismatch of the API for their gateway which 
>>> discourages the effort to use the API.
>>> 
>>> IMO part of our Thrift API effort should be to document these with 
>>> the solutions similar to Java Patterns.
>>> 
>>> In short, instead of trying to come up with a general API to make
>> everyone
>>> happy we provide solution patterns for a gateway use case which will 
>>> have multiple variations. (solution pattern would be use of the API 
>>> +
>> supporting
>>> code which handles the variation)
>>> 
>>> wdyt?
>>> 
>>> 
>>> Regards,
>>> 
>>> Saminda
>>> 
>> 


RE: Documenting Airavata API usage patterns

Posted by "Miller, Mark" <mm...@sdsc.edu>.
Although I am non-technical, I would just like to say that (IMO) the issues Saminda is raising here and our ability to finesse them as a group 
will be the single most important determinants of SciGap success or failure as a project and a software package.

-----Original Message-----
From: Saminda Wijeratne [mailto:samindaw@gmail.com] 
Sent: Thursday, January 30, 2014 11:35 PM
To: architecture
Subject: Re: Documenting Airavata API usage patterns

I agree with your argument on identifying the focus groups and their needs and figuring out how to solve their problems. Figuring out a simple API is indeed important. My concern was more towards the next step. How to present our solution to the users. Having a well-defined API covering the required functionalities not necessarily can be made simple enough to be understood or doesn't explain most of the time how to arrive at a point where they can be used. For instance designing a function to retrieve experiment data requires us to understand atleast the level of granularity of the data expected, filtrations to be considered and the frequency of invocations.

On the few gateways I've worked so far (ParamChem, Ultrascan and
CIPRES/NSG) I didn't see the direct usage of the current API. While in each case API showed alot of strength in certain areas where it made developer life really easy, most of the time they had to go through a few hops to actually to reach the use of API (and most of the time this is with our help). These hops are not always obvious and time it takes to figuring them out could be the difference between giving up or making a commitment to learn Airavata API nooks and corners. My point is that we can reduce this time by documenting what we already know on different variations of the same use case.

My recent experience on CIPRES + Airavata integration is a good example why I'm proposing this. CIPRES has a different pluggable framework of handling jobs and their data compared to Airavata. It took me a while to understand how Airavata can be plugged in to CIPRES even with my knowledge of Airavata and (limited though) CIPRES. Eventhough it wouldn't be an ideal way of integrating Airavata to CIPRES (one too many levels of abstractions) the resultant implementation is infact simple enough to understand to a gateway dev. But the fact is I had to spend alot of time getting to that solution.
It was the same case with the ParamChem integration (although it took less time).


On Thu, Jan 30, 2014 at 10:18 PM, Eran Chinthaka Withana < eran.chinthaka@gmail.com> wrote:

> Hi Saminda,
>
> There are two major points we need to address to answer your question.
>
> 1. who are we trying to cater and what they want 2. once we know what 
> we want from #1 above how do we achieve it
>
> #1: We can either make it easy for the scientists who use the gateway 
> or make it easy for the developer, i.e. you. I think one of the major 
> selling points for science gateways like Airavata is that it will make 
> the life of a non-computer scientist easy by abstracting away the 
> complexities of gateways. A common example we used to mention when we 
> were in IU is that Sun Kim (a bio scientist in IU) should better spend 
> his time trying to improve his algorithms than trying to tackle with 
> WS-GRAM. Also, he should not worry too much when he decide to run an 
> application in BigRed (if its still there :) ) vs NCSA vs Prof. Fox's 
> windows HPC cluster. It should ideally be just a matter of flipping a 
> switch in the API (but yes there will be some pre-preparation, like 
> installing apps, before doing this). I think we should give priority 
> to make it easy for the clients. So, if we agree on this with the 
> conclusion that the scientists, i.e. Airavata clients are hidden from 
> the underlying job submission mechanisms then we can tackle #2.
>
> #2: When I was working with Sigiri (in my previous life) I had the 
> same problem. I had two main methods to accomplish that.
> 1. I looked into solutions like JSDL (
> http://en.wikipedia.org/wiki/Job_Submission_Description_Language) 
> which had already come up with an abstraction. But this was kind of 
> biased towards Grids.
> 2. I looked into some of the existing gateways to define a generic API
>
> At the end, I ended up defining a generic API from what I learnt from 
> both methods but making sure the client API is simple. The API 1. 
> simple enough to submit simple jobs that are covering about 80% of the 
> use cases (including parametric sweeps) 2. extensible enough to cover 
> the corner cases which amounted to about 20% of the use cases
>
> Within the implementations of each gateway, I had Adapters for each 
> gateway and were picked based on what clients need. I can go into 
> details if needed (and I need to go back to code) but this is something worth considering.
>
> BTW, I understand the fact that the Airavata thrift API may be "hidden"
> underneath XBaya but I'm sure there will be usecases where some 
> scientists (and their poor grad students) wanting to launch workflows 
> programmatically using thrift API.
>
> Thanks,
> Eran Chinthaka Withana
>
>
> On Thu, Jan 30, 2014 at 8:54 PM, Saminda Wijeratne <samindaw@gmail.com
> >wrote:
>
> > I'm thinking of the reasons why we are having trouble getting a 
> > proper
> API
> > to work smoothly is that,
> >
> >
> >    1. We are trying too hard to generalize when its probably not possible
> >    to do
> >    2. When we keep trying to see the big picture we miss the little
> things
> >    in the gateways that makes the usage of the API easy or hard for the
> >    developer.
> >
> > eg: Not all gateways look at "Experiment Launch" use case as passing 
> > an application name and its input to launch the experiment. (I think 
> > we've came across many variations for this use case)
> >
> >    - the inputs could be in different form (could be actual files) 
> > or
> just
> >    optional
> >    - application name could be just a reference to a parameter of a
> global
> >    application
> >    - part of the launch process may have runtime dependencies which
> gateway
> >    requires to participate
> >    - the gateway might want more control over the launch 
> > configurations
> at
> >    runtime.
> >    - ...
> >
> > I think devs see it as a mismatch of the API for their gateway which 
> > discourages the effort to use the API.
> >
> > IMO part of our Thrift API effort should be to document these with 
> > the solutions similar to Java Patterns.
> >
> > In short, instead of trying to come up with a general API to make
> everyone
> > happy we provide solution patterns for a gateway use case which will 
> > have multiple variations. (solution pattern would be use of the API 
> > +
> supporting
> > code which handles the variation)
> >
> > wdyt?
> >
> >
> > Regards,
> >
> > Saminda
> >
>

Re: Documenting Airavata API usage patterns

Posted by Saminda Wijeratne <sa...@gmail.com>.
On Fri, Jan 31, 2014 at 6:38 AM, Marlon Pierce <ma...@iu.edu> wrote:

> There are two communities of gateway developers. The first includes
> CIPRES, NSG, UltraScan, ParamChem, GridChem, etc. These groups already
> have something in place and we are looking at how to work with them.
> Matching Airavata with any one (much less all three) is a technical
> challenge for reasons you know well.  This is a job for an Airavata
> specialist to integrate, but once done it has a large payoff in usage.
>
Exactly. For each gateway the effort put has gone through several
iterations to arrive at an optimal usage of the API. These different
solutions should be made available (perhaps on wiki) to public so that next
time it wouldn't take an Airavata specialist (or a rocket scientist -
whichever sounds cooler) to repeat the solution to a similar gateway.

>
> The second group is the group who is just starting out and wants to be
> told what to do to get started.  Integrating with these groups is
> different: they'll do what we recommend, so we need to have good
> documentation on common gateway development patterns.  This is (I think)
> Saminda's next step.
>
Which reminds me, I think we should have a simple guide on "How to develop
a gateway" in the wiki. I dont think we need to go in to details, but
bullet points and links would suffice. I'm sure the gateways we worked with
so far would be happy to chip in with some ideas on how to do this.
Sachiths "Gateway Developer Guide" wiki page will be very valuable here.

>
> A spinoff of the second group is the group who wants to clone one of the
> gateways above for their own community. In this case, they may never
> touch the API, so the work to make things work well for our favorite
> gateways is doubly rewarded.
>
> A spinoff of the first group is one that decides to make a major version
> iteration of their code and program more directly to the API.  There's a
> lot of effort here, but on the other hand gateways accumulate
> workarounds, new use cases, new resources, new problems, etc that may
> eventually make the major version upgrade worth the effort.
>
Totally agree. The gateway developer can then focus on their main objective
of catering the gateway community rather than for instance managing remote
resources.

>
> So my conclusion is that the API will need to be complicated before it
> is simple. Part of the reason gateways do things that make things
> complicated for your API work is that they were working in isolation
> from other gateways in their design.  If we are successful, we will help
> these gateways converge on common abstractions, but this will take some
> time.  In the meantime, we should document a simple path through the API
> that accommodates new developers starting from scratch.
>
> Marlon
>
> On 1/31/14 2:35 AM, Saminda Wijeratne wrote:
> > I agree with your argument on identifying the focus groups and their
> needs
> > and figuring out how to solve their problems. Figuring out a simple API
> is
> > indeed important. My concern was more towards the next step. How to
> present
> > our solution to the users. Having a well-defined API covering the
> required
> > functionalities not necessarily can be made simple enough to be
> understood
> > or doesn't explain most of the time how to arrive at a point where they
> can
> > be used. For instance designing a function to retrieve experiment data
> > requires us to understand atleast the level of granularity of the data
> > expected, filtrations to be considered and the frequency of invocations.
> >
> > On the few gateways I've worked so far (ParamChem, Ultrascan and
> > CIPRES/NSG) I didn't see the direct usage of the current API. While in
> each
> > case API showed alot of strength in certain areas where it made developer
> > life really easy, most of the time they had to go through a few hops to
> > actually to reach the use of API (and most of the time this is with our
> > help). These hops are not always obvious and time it takes to figuring
> them
> > out could be the difference between giving up or making a commitment to
> > learn Airavata API nooks and corners. My point is that we can reduce this
> > time by documenting what we already know on different variations of the
> > same use case.
> >
> > My recent experience on CIPRES + Airavata integration is a good example
> why
> > I'm proposing this. CIPRES has a different pluggable framework of
> handling
> > jobs and their data compared to Airavata. It took me a while to
> understand
> > how Airavata can be plugged in to CIPRES even with my knowledge of
> Airavata
> > and (limited though) CIPRES. Eventhough it wouldn't be an ideal way of
> > integrating Airavata to CIPRES (one too many levels of abstractions) the
> > resultant implementation is infact simple enough to understand to a
> gateway
> > dev. But the fact is I had to spend alot of time getting to that
> solution.
> > It was the same case with the ParamChem integration (although it took
> less
> > time).
> >
> >
> > On Thu, Jan 30, 2014 at 10:18 PM, Eran Chinthaka Withana <
> > eran.chinthaka@gmail.com> wrote:
> >
> >> Hi Saminda,
> >>
> >> There are two major points we need to address to answer your question.
> >>
> >> 1. who are we trying to cater and what they want
> >> 2. once we know what we want from #1 above how do we achieve it
> >>
> >> #1: We can either make it easy for the scientists who use the gateway or
> >> make it easy for the developer, i.e. you. I think one of the major
> selling
> >> points for science gateways like Airavata is that it will make the life
> of
> >> a non-computer scientist easy by abstracting away the complexities of
> >> gateways. A common example we used to mention when we were in IU is that
> >> Sun Kim (a bio scientist in IU) should better spend his time trying to
> >> improve his algorithms than trying to tackle with WS-GRAM. Also, he
> should
> >> not worry too much when he decide to run an application in BigRed (if
> its
> >> still there :) ) vs NCSA vs Prof. Fox's windows HPC cluster. It should
> >> ideally be just a matter of flipping a switch in the API (but yes there
> >> will be some pre-preparation, like installing apps, before doing this).
> I
> >> think we should give priority to make it easy for the clients. So, if we
> >> agree on this with the conclusion that the scientists, i.e. Airavata
> >> clients are hidden from the underlying job submission mechanisms then we
> >> can tackle #2.
> >>
> >> #2: When I was working with Sigiri (in my previous life) I had the same
> >> problem. I had two main methods to accomplish that.
> >> 1. I looked into solutions like JSDL (
> >> http://en.wikipedia.org/wiki/Job_Submission_Description_Language) which
> >> had
> >> already come up with an abstraction. But this was kind of biased towards
> >> Grids.
> >> 2. I looked into some of the existing gateways to define a generic API
> >>
> >> At the end, I ended up defining a generic API from what I learnt from
> both
> >> methods but making sure the client API is simple. The API
> >> 1. simple enough to submit simple jobs that are covering about 80% of
> the
> >> use cases (including parametric sweeps)
> >> 2. extensible enough to cover the corner cases which amounted to about
> 20%
> >> of the use cases
> >>
> >> Within the implementations of each gateway, I had Adapters for each
> gateway
> >> and were picked based on what clients need. I can go into details if
> needed
> >> (and I need to go back to code) but this is something worth considering.
> >>
> >> BTW, I understand the fact that the Airavata thrift API may be "hidden"
> >> underneath XBaya but I'm sure there will be usecases where some
> scientists
> >> (and their poor grad students) wanting to launch workflows
> programmatically
> >> using thrift API.
> >>
> >> Thanks,
> >> Eran Chinthaka Withana
> >>
> >>
> >> On Thu, Jan 30, 2014 at 8:54 PM, Saminda Wijeratne <samindaw@gmail.com
> >>> wrote:
> >>> I'm thinking of the reasons why we are having trouble getting a proper
> >> API
> >>> to work smoothly is that,
> >>>
> >>>
> >>>    1. We are trying too hard to generalize when its probably not
> possible
> >>>    to do
> >>>    2. When we keep trying to see the big picture we miss the little
> >> things
> >>>    in the gateways that makes the usage of the API easy or hard for the
> >>>    developer.
> >>>
> >>> eg: Not all gateways look at "Experiment Launch" use case as passing an
> >>> application name and its input to launch the experiment. (I think we've
> >>> came across many variations for this use case)
> >>>
> >>>    - the inputs could be in different form (could be actual files) or
> >> just
> >>>    optional
> >>>    - application name could be just a reference to a parameter of a
> >> global
> >>>    application
> >>>    - part of the launch process may have runtime dependencies which
> >> gateway
> >>>    requires to participate
> >>>    - the gateway might want more control over the launch configurations
> >> at
> >>>    runtime.
> >>>    - ...
> >>>
> >>> I think devs see it as a mismatch of the API for their gateway which
> >>> discourages the effort to use the API.
> >>>
> >>> IMO part of our Thrift API effort should be to document these with the
> >>> solutions similar to Java Patterns.
> >>>
> >>> In short, instead of trying to come up with a general API to make
> >> everyone
> >>> happy we provide solution patterns for a gateway use case which will
> have
> >>> multiple variations. (solution pattern would be use of the API +
> >> supporting
> >>> code which handles the variation)
> >>>
> >>> wdyt?
> >>>
> >>>
> >>> Regards,
> >>>
> >>> Saminda
> >>>
>
>

Re: Documenting Airavata API usage patterns

Posted by Marlon Pierce <ma...@iu.edu>.
There are two communities of gateway developers. The first includes
CIPRES, NSG, UltraScan, ParamChem, GridChem, etc. These groups already
have something in place and we are looking at how to work with them. 
Matching Airavata with any one (much less all three) is a technical
challenge for reasons you know well.  This is a job for an Airavata
specialist to integrate, but once done it has a large payoff in usage.

The second group is the group who is just starting out and wants to be
told what to do to get started.  Integrating with these groups is
different: they'll do what we recommend, so we need to have good
documentation on common gateway development patterns.  This is (I think)
Saminda's next step.

A spinoff of the second group is the group who wants to clone one of the
gateways above for their own community. In this case, they may never
touch the API, so the work to make things work well for our favorite
gateways is doubly rewarded.

A spinoff of the first group is one that decides to make a major version
iteration of their code and program more directly to the API.  There's a
lot of effort here, but on the other hand gateways accumulate
workarounds, new use cases, new resources, new problems, etc that may
eventually make the major version upgrade worth the effort.

So my conclusion is that the API will need to be complicated before it
is simple. Part of the reason gateways do things that make things
complicated for your API work is that they were working in isolation
from other gateways in their design.  If we are successful, we will help
these gateways converge on common abstractions, but this will take some
time.  In the meantime, we should document a simple path through the API
that accommodates new developers starting from scratch.

Marlon

On 1/31/14 2:35 AM, Saminda Wijeratne wrote:
> I agree with your argument on identifying the focus groups and their needs
> and figuring out how to solve their problems. Figuring out a simple API is
> indeed important. My concern was more towards the next step. How to present
> our solution to the users. Having a well-defined API covering the required
> functionalities not necessarily can be made simple enough to be understood
> or doesn't explain most of the time how to arrive at a point where they can
> be used. For instance designing a function to retrieve experiment data
> requires us to understand atleast the level of granularity of the data
> expected, filtrations to be considered and the frequency of invocations.
>
> On the few gateways I've worked so far (ParamChem, Ultrascan and
> CIPRES/NSG) I didn't see the direct usage of the current API. While in each
> case API showed alot of strength in certain areas where it made developer
> life really easy, most of the time they had to go through a few hops to
> actually to reach the use of API (and most of the time this is with our
> help). These hops are not always obvious and time it takes to figuring them
> out could be the difference between giving up or making a commitment to
> learn Airavata API nooks and corners. My point is that we can reduce this
> time by documenting what we already know on different variations of the
> same use case.
>
> My recent experience on CIPRES + Airavata integration is a good example why
> I'm proposing this. CIPRES has a different pluggable framework of handling
> jobs and their data compared to Airavata. It took me a while to understand
> how Airavata can be plugged in to CIPRES even with my knowledge of Airavata
> and (limited though) CIPRES. Eventhough it wouldn't be an ideal way of
> integrating Airavata to CIPRES (one too many levels of abstractions) the
> resultant implementation is infact simple enough to understand to a gateway
> dev. But the fact is I had to spend alot of time getting to that solution.
> It was the same case with the ParamChem integration (although it took less
> time).
>
>
> On Thu, Jan 30, 2014 at 10:18 PM, Eran Chinthaka Withana <
> eran.chinthaka@gmail.com> wrote:
>
>> Hi Saminda,
>>
>> There are two major points we need to address to answer your question.
>>
>> 1. who are we trying to cater and what they want
>> 2. once we know what we want from #1 above how do we achieve it
>>
>> #1: We can either make it easy for the scientists who use the gateway or
>> make it easy for the developer, i.e. you. I think one of the major selling
>> points for science gateways like Airavata is that it will make the life of
>> a non-computer scientist easy by abstracting away the complexities of
>> gateways. A common example we used to mention when we were in IU is that
>> Sun Kim (a bio scientist in IU) should better spend his time trying to
>> improve his algorithms than trying to tackle with WS-GRAM. Also, he should
>> not worry too much when he decide to run an application in BigRed (if its
>> still there :) ) vs NCSA vs Prof. Fox's windows HPC cluster. It should
>> ideally be just a matter of flipping a switch in the API (but yes there
>> will be some pre-preparation, like installing apps, before doing this). I
>> think we should give priority to make it easy for the clients. So, if we
>> agree on this with the conclusion that the scientists, i.e. Airavata
>> clients are hidden from the underlying job submission mechanisms then we
>> can tackle #2.
>>
>> #2: When I was working with Sigiri (in my previous life) I had the same
>> problem. I had two main methods to accomplish that.
>> 1. I looked into solutions like JSDL (
>> http://en.wikipedia.org/wiki/Job_Submission_Description_Language) which
>> had
>> already come up with an abstraction. But this was kind of biased towards
>> Grids.
>> 2. I looked into some of the existing gateways to define a generic API
>>
>> At the end, I ended up defining a generic API from what I learnt from both
>> methods but making sure the client API is simple. The API
>> 1. simple enough to submit simple jobs that are covering about 80% of the
>> use cases (including parametric sweeps)
>> 2. extensible enough to cover the corner cases which amounted to about 20%
>> of the use cases
>>
>> Within the implementations of each gateway, I had Adapters for each gateway
>> and were picked based on what clients need. I can go into details if needed
>> (and I need to go back to code) but this is something worth considering.
>>
>> BTW, I understand the fact that the Airavata thrift API may be "hidden"
>> underneath XBaya but I'm sure there will be usecases where some scientists
>> (and their poor grad students) wanting to launch workflows programmatically
>> using thrift API.
>>
>> Thanks,
>> Eran Chinthaka Withana
>>
>>
>> On Thu, Jan 30, 2014 at 8:54 PM, Saminda Wijeratne <samindaw@gmail.com
>>> wrote:
>>> I'm thinking of the reasons why we are having trouble getting a proper
>> API
>>> to work smoothly is that,
>>>
>>>
>>>    1. We are trying too hard to generalize when its probably not possible
>>>    to do
>>>    2. When we keep trying to see the big picture we miss the little
>> things
>>>    in the gateways that makes the usage of the API easy or hard for the
>>>    developer.
>>>
>>> eg: Not all gateways look at "Experiment Launch" use case as passing an
>>> application name and its input to launch the experiment. (I think we've
>>> came across many variations for this use case)
>>>
>>>    - the inputs could be in different form (could be actual files) or
>> just
>>>    optional
>>>    - application name could be just a reference to a parameter of a
>> global
>>>    application
>>>    - part of the launch process may have runtime dependencies which
>> gateway
>>>    requires to participate
>>>    - the gateway might want more control over the launch configurations
>> at
>>>    runtime.
>>>    - ...
>>>
>>> I think devs see it as a mismatch of the API for their gateway which
>>> discourages the effort to use the API.
>>>
>>> IMO part of our Thrift API effort should be to document these with the
>>> solutions similar to Java Patterns.
>>>
>>> In short, instead of trying to come up with a general API to make
>> everyone
>>> happy we provide solution patterns for a gateway use case which will have
>>> multiple variations. (solution pattern would be use of the API +
>> supporting
>>> code which handles the variation)
>>>
>>> wdyt?
>>>
>>>
>>> Regards,
>>>
>>> Saminda
>>>


Re: Documenting Airavata API usage patterns

Posted by Saminda Wijeratne <sa...@gmail.com>.
I agree with your argument on identifying the focus groups and their needs
and figuring out how to solve their problems. Figuring out a simple API is
indeed important. My concern was more towards the next step. How to present
our solution to the users. Having a well-defined API covering the required
functionalities not necessarily can be made simple enough to be understood
or doesn't explain most of the time how to arrive at a point where they can
be used. For instance designing a function to retrieve experiment data
requires us to understand atleast the level of granularity of the data
expected, filtrations to be considered and the frequency of invocations.

On the few gateways I've worked so far (ParamChem, Ultrascan and
CIPRES/NSG) I didn't see the direct usage of the current API. While in each
case API showed alot of strength in certain areas where it made developer
life really easy, most of the time they had to go through a few hops to
actually to reach the use of API (and most of the time this is with our
help). These hops are not always obvious and time it takes to figuring them
out could be the difference between giving up or making a commitment to
learn Airavata API nooks and corners. My point is that we can reduce this
time by documenting what we already know on different variations of the
same use case.

My recent experience on CIPRES + Airavata integration is a good example why
I'm proposing this. CIPRES has a different pluggable framework of handling
jobs and their data compared to Airavata. It took me a while to understand
how Airavata can be plugged in to CIPRES even with my knowledge of Airavata
and (limited though) CIPRES. Eventhough it wouldn't be an ideal way of
integrating Airavata to CIPRES (one too many levels of abstractions) the
resultant implementation is infact simple enough to understand to a gateway
dev. But the fact is I had to spend alot of time getting to that solution.
It was the same case with the ParamChem integration (although it took less
time).


On Thu, Jan 30, 2014 at 10:18 PM, Eran Chinthaka Withana <
eran.chinthaka@gmail.com> wrote:

> Hi Saminda,
>
> There are two major points we need to address to answer your question.
>
> 1. who are we trying to cater and what they want
> 2. once we know what we want from #1 above how do we achieve it
>
> #1: We can either make it easy for the scientists who use the gateway or
> make it easy for the developer, i.e. you. I think one of the major selling
> points for science gateways like Airavata is that it will make the life of
> a non-computer scientist easy by abstracting away the complexities of
> gateways. A common example we used to mention when we were in IU is that
> Sun Kim (a bio scientist in IU) should better spend his time trying to
> improve his algorithms than trying to tackle with WS-GRAM. Also, he should
> not worry too much when he decide to run an application in BigRed (if its
> still there :) ) vs NCSA vs Prof. Fox's windows HPC cluster. It should
> ideally be just a matter of flipping a switch in the API (but yes there
> will be some pre-preparation, like installing apps, before doing this). I
> think we should give priority to make it easy for the clients. So, if we
> agree on this with the conclusion that the scientists, i.e. Airavata
> clients are hidden from the underlying job submission mechanisms then we
> can tackle #2.
>
> #2: When I was working with Sigiri (in my previous life) I had the same
> problem. I had two main methods to accomplish that.
> 1. I looked into solutions like JSDL (
> http://en.wikipedia.org/wiki/Job_Submission_Description_Language) which
> had
> already come up with an abstraction. But this was kind of biased towards
> Grids.
> 2. I looked into some of the existing gateways to define a generic API
>
> At the end, I ended up defining a generic API from what I learnt from both
> methods but making sure the client API is simple. The API
> 1. simple enough to submit simple jobs that are covering about 80% of the
> use cases (including parametric sweeps)
> 2. extensible enough to cover the corner cases which amounted to about 20%
> of the use cases
>
> Within the implementations of each gateway, I had Adapters for each gateway
> and were picked based on what clients need. I can go into details if needed
> (and I need to go back to code) but this is something worth considering.
>
> BTW, I understand the fact that the Airavata thrift API may be "hidden"
> underneath XBaya but I'm sure there will be usecases where some scientists
> (and their poor grad students) wanting to launch workflows programmatically
> using thrift API.
>
> Thanks,
> Eran Chinthaka Withana
>
>
> On Thu, Jan 30, 2014 at 8:54 PM, Saminda Wijeratne <samindaw@gmail.com
> >wrote:
>
> > I'm thinking of the reasons why we are having trouble getting a proper
> API
> > to work smoothly is that,
> >
> >
> >    1. We are trying too hard to generalize when its probably not possible
> >    to do
> >    2. When we keep trying to see the big picture we miss the little
> things
> >    in the gateways that makes the usage of the API easy or hard for the
> >    developer.
> >
> > eg: Not all gateways look at "Experiment Launch" use case as passing an
> > application name and its input to launch the experiment. (I think we've
> > came across many variations for this use case)
> >
> >    - the inputs could be in different form (could be actual files) or
> just
> >    optional
> >    - application name could be just a reference to a parameter of a
> global
> >    application
> >    - part of the launch process may have runtime dependencies which
> gateway
> >    requires to participate
> >    - the gateway might want more control over the launch configurations
> at
> >    runtime.
> >    - ...
> >
> > I think devs see it as a mismatch of the API for their gateway which
> > discourages the effort to use the API.
> >
> > IMO part of our Thrift API effort should be to document these with the
> > solutions similar to Java Patterns.
> >
> > In short, instead of trying to come up with a general API to make
> everyone
> > happy we provide solution patterns for a gateway use case which will have
> > multiple variations. (solution pattern would be use of the API +
> supporting
> > code which handles the variation)
> >
> > wdyt?
> >
> >
> > Regards,
> >
> > Saminda
> >
>

Re: Documenting Airavata API usage patterns

Posted by Eran Chinthaka Withana <er...@gmail.com>.
Hi Saminda,

There are two major points we need to address to answer your question.

1. who are we trying to cater and what they want
2. once we know what we want from #1 above how do we achieve it

#1: We can either make it easy for the scientists who use the gateway or
make it easy for the developer, i.e. you. I think one of the major selling
points for science gateways like Airavata is that it will make the life of
a non-computer scientist easy by abstracting away the complexities of
gateways. A common example we used to mention when we were in IU is that
Sun Kim (a bio scientist in IU) should better spend his time trying to
improve his algorithms than trying to tackle with WS-GRAM. Also, he should
not worry too much when he decide to run an application in BigRed (if its
still there :) ) vs NCSA vs Prof. Fox's windows HPC cluster. It should
ideally be just a matter of flipping a switch in the API (but yes there
will be some pre-preparation, like installing apps, before doing this). I
think we should give priority to make it easy for the clients. So, if we
agree on this with the conclusion that the scientists, i.e. Airavata
clients are hidden from the underlying job submission mechanisms then we
can tackle #2.

#2: When I was working with Sigiri (in my previous life) I had the same
problem. I had two main methods to accomplish that.
1. I looked into solutions like JSDL (
http://en.wikipedia.org/wiki/Job_Submission_Description_Language) which had
already come up with an abstraction. But this was kind of biased towards
Grids.
2. I looked into some of the existing gateways to define a generic API

At the end, I ended up defining a generic API from what I learnt from both
methods but making sure the client API is simple. The API
1. simple enough to submit simple jobs that are covering about 80% of the
use cases (including parametric sweeps)
2. extensible enough to cover the corner cases which amounted to about 20%
of the use cases

Within the implementations of each gateway, I had Adapters for each gateway
and were picked based on what clients need. I can go into details if needed
(and I need to go back to code) but this is something worth considering.

BTW, I understand the fact that the Airavata thrift API may be "hidden"
underneath XBaya but I'm sure there will be usecases where some scientists
(and their poor grad students) wanting to launch workflows programmatically
using thrift API.

Thanks,
Eran Chinthaka Withana


On Thu, Jan 30, 2014 at 8:54 PM, Saminda Wijeratne <sa...@gmail.com>wrote:

> I'm thinking of the reasons why we are having trouble getting a proper API
> to work smoothly is that,
>
>
>    1. We are trying too hard to generalize when its probably not possible
>    to do
>    2. When we keep trying to see the big picture we miss the little things
>    in the gateways that makes the usage of the API easy or hard for the
>    developer.
>
> eg: Not all gateways look at "Experiment Launch" use case as passing an
> application name and its input to launch the experiment. (I think we've
> came across many variations for this use case)
>
>    - the inputs could be in different form (could be actual files) or just
>    optional
>    - application name could be just a reference to a parameter of a global
>    application
>    - part of the launch process may have runtime dependencies which gateway
>    requires to participate
>    - the gateway might want more control over the launch configurations at
>    runtime.
>    - ...
>
> I think devs see it as a mismatch of the API for their gateway which
> discourages the effort to use the API.
>
> IMO part of our Thrift API effort should be to document these with the
> solutions similar to Java Patterns.
>
> In short, instead of trying to come up with a general API to make everyone
> happy we provide solution patterns for a gateway use case which will have
> multiple variations. (solution pattern would be use of the API + supporting
> code which handles the variation)
>
> wdyt?
>
>
> Regards,
>
> Saminda
>

Re: Documenting Airavata API usage patterns

Posted by Saminda Wijeratne <sa...@gmail.com>.
On Fri, Jan 31, 2014 at 6:39 AM, Suresh Marru <sm...@apache.org> wrote:

> Great initiation Saminda, this is a key usability topic and especially
> when you refresh people's past lives you hit it right on :)
>
> Firstly lets refer to Airavata Stakeholders diagram [1], I assume we are
> talking about Gateway Developers who will program against the Airavata
> Client SDK. Just to confirm, I do not think the concern is if Generic
> Software Frameworks will meet the diverse goals of science gateways right?
> With so many use cases applied to Airavata I hope its evident that it can
> be infact be done. Eran's summary of 80% of classic use cases and
> extensibility to meet the 20% corner cases is a good one. Infact, may be we
> only should say 10% of advanced use cases and Airavata cannot (not worth
> the additional complexity) meet the last 10% of corner cases.
>
I think you raised an important point here Suresh. For example while
Airavata is perfectly capable of downloading output files/folders in a
remote machine to users desktop or to the portal server it could be just
more efficient to do such things without a middleman.

>
> If the discussion is about the best practices to document the use of API
> (not just API documents, but good use case documents), then here are couple
> of approaches to consider.
>
> To address a similar challenging goals for scientific workflows (a first
> cousin of gateways) we first identified various usage paradigms [2], then
> gathered vignettes from community [3] to illustrate these paradigms for
> real-world use cases.
>
> In a different world, we tried to approach this problem writing a online
> cookbook (trying not to have them outdated for long) where each recipes
> will describe an approach to build a gateways. So a new gateways comes on,
> they look at these recipes and find the closest matching one and mimic it.
>
> So based on these, what I am proposing for Airavata is:
> * Lets define various known usage paradigms,
> * Solicit vignettes from community
> * Develop and maintain a Airavata Cookbook, with each recipe pointing to
> sample code and will have a corresponding integration test to make sure the
> samples work as the software evolves through releases.
>
+1.
You are better at explaining this than I'm :)

>
> Comments?
>
> Suresh
> [1] - http://airavata.apache.org/architecture/airavata-stakeholders.html
> [2] -
> https://sites.google.com/site/earthcubeworkflow/workflow-background/workflow-use-paradigms
> [3] - https://sites.google.com/site/earthcubeworkflow/workflow-vignettes
> [4] -
> http://www.isi.edu/~gil/EarthCube/EC-WorkflowsRoadmap-September2012.pdf
> [5] - https://www.xsede.org/web/gateways/gateways-cookbook
> [6] -
> https://www.xsede.org/web/gateways/gateways-cookbook/-/wikid/f5zI/Cookbook/CIPRES+Science+Gateway+Recipe
>
> On Jan 31, 2014, at 3:00 AM, Saminda Wijeratne <sa...@gmail.com> wrote:
>
> > On Thu, Jan 30, 2014 at 9:34 PM, Amila Jayasekara
> > <th...@gmail.com>wrote:
> >
> >> We definitely need sample code which demonstrate the use of Airavata
> API.
> >> But I am not sure whether to call them patterns or API documentation.
> >>
> > Its definitely not API documentation. We so far have solve several
> gateway
> > problems using Airavata and and each is different on its own although the
> > ultimate goal was the same. I just think that it would be very useful to
> > have these variations documented. I used the word "pattern" because even
> > with different variations there will be other gateways which may be
> > following the same variation. Thus the word "pattern".
> >
> >>
> >> We do not need to create a "very" generic API but the API should be
> >> intuitive enough for a person with high-level picture in mind to
> understand
> >> and guess which functions to call to get something done.
> >>
> > In my experience these days most developers google for
> > examples/solutions/algorithms (atleast to get an idea how to do
> something)
> > rather than go through API documentations and designing and implementing
> > from scratch. And the Airavata API (Thrift version or otherwise)
> inherits a
> > context of usage which pops the questions like "when to use what and
> how".
> > There is so many features just for an Airavata experiment launch which we
> > have implemented because of user requirements which we cannot expect
> users
> > to be intuitive enough to figure-out the importance of using them when,
> why
> > and how.
> >
> >
> >> Thanks
> >> Amila
> >>
> >>
> >> On Thu, Jan 30, 2014 at 11:54 PM, Saminda Wijeratne <samindaw@gmail.com
> >>> wrote:
> >>
> >>> I'm thinking of the reasons why we are having trouble getting a proper
> >> API
> >>> to work smoothly is that,
> >>>
> >>>
> >>>   1. We are trying too hard to generalize when its probably not
> possible
> >>>   to do
> >>>   2. When we keep trying to see the big picture we miss the little
> >> things
> >>>   in the gateways that makes the usage of the API easy or hard for the
> >>>   developer.
> >>>
> >>> eg: Not all gateways look at "Experiment Launch" use case as passing an
> >>> application name and its input to launch the experiment. (I think we've
> >>> came across many variations for this use case)
> >>>
> >>>   - the inputs could be in different form (could be actual files) or
> >> just
> >>>   optional
> >>>   - application name could be just a reference to a parameter of a
> >> global
> >>>   application
> >>>   - part of the launch process may have runtime dependencies which
> >> gateway
> >>>   requires to participate
> >>>   - the gateway might want more control over the launch configurations
> >> at
> >>>   runtime.
> >>>   - ...
> >>>
> >>> I think devs see it as a mismatch of the API for their gateway which
> >>> discourages the effort to use the API.
> >>>
> >>> IMO part of our Thrift API effort should be to document these with the
> >>> solutions similar to Java Patterns.
> >>>
> >>> In short, instead of trying to come up with a general API to make
> >> everyone
> >>> happy we provide solution patterns for a gateway use case which will
> have
> >>> multiple variations. (solution pattern would be use of the API +
> >> supporting
> >>> code which handles the variation)
> >>>
> >>> wdyt?
> >>>
> >>>
> >>> Regards,
> >>>
> >>> Saminda
> >>>
> >>
>
>

Re: Documenting Airavata API usage patterns

Posted by Suresh Marru <sm...@apache.org>.
Great initiation Saminda, this is a key usability topic and especially when you refresh people’s past lives you hit it right on :)

Firstly lets refer to Airavata Stakeholders diagram [1], I assume we are talking about Gateway Developers who will program against the Airavata Client SDK. Just to confirm, I do not think the concern is if Generic Software Frameworks will meet the diverse goals of science gateways right? With so many use cases applied to Airavata I hope its evident that it can be infact be done. Eran’s summary of 80% of classic use cases and extensibility to meet the 20% corner cases is a good one. Infact, may be we only should say 10% of advanced use cases and Airavata cannot (not worth the additional complexity) meet the last 10% of corner cases. 

If the discussion is about the best practices to document the use of API (not just API documents, but good use case documents), then here are couple of approaches to consider.

To address a similar challenging goals for scientific workflows (a first cousin of gateways) we first identified various usage paradigms [2], then gathered vignettes from community [3] to illustrate these paradigms for real-world use cases. 

In a different world, we tried to approach this problem writing a online cookbook (trying not to have them outdated for long) where each recipes will describe an approach to build a gateways. So a new gateways comes on, they look at these recipes and find the closest matching one and mimic it.

So based on these, what I am proposing for Airavata is:
* Lets define various known usage paradigms, 
* Solicit vignettes from community 
* Develop and maintain a Airavata Cookbook, with each recipe pointing to sample code and will have a corresponding integration test to make sure the samples work as the software evolves through releases.

Comments?

Suresh
[1] - http://airavata.apache.org/architecture/airavata-stakeholders.html
[2] - https://sites.google.com/site/earthcubeworkflow/workflow-background/workflow-use-paradigms
[3] - https://sites.google.com/site/earthcubeworkflow/workflow-vignettes
[4] - http://www.isi.edu/~gil/EarthCube/EC-WorkflowsRoadmap-September2012.pdf
[5] - https://www.xsede.org/web/gateways/gateways-cookbook
[6] - https://www.xsede.org/web/gateways/gateways-cookbook/-/wikid/f5zI/Cookbook/CIPRES+Science+Gateway+Recipe

On Jan 31, 2014, at 3:00 AM, Saminda Wijeratne <sa...@gmail.com> wrote:

> On Thu, Jan 30, 2014 at 9:34 PM, Amila Jayasekara
> <th...@gmail.com>wrote:
> 
>> We definitely need sample code which demonstrate the use of Airavata API.
>> But I am not sure whether to call them patterns or API documentation.
>> 
> Its definitely not API documentation. We so far have solve several gateway
> problems using Airavata and and each is different on its own although the
> ultimate goal was the same. I just think that it would be very useful to
> have these variations documented. I used the word "pattern" because even
> with different variations there will be other gateways which may be
> following the same variation. Thus the word "pattern".
> 
>> 
>> We do not need to create a "very" generic API but the API should be
>> intuitive enough for a person with high-level picture in mind to understand
>> and guess which functions to call to get something done.
>> 
> In my experience these days most developers google for
> examples/solutions/algorithms (atleast to get an idea how to do something)
> rather than go through API documentations and designing and implementing
> from scratch. And the Airavata API (Thrift version or otherwise) inherits a
> context of usage which pops the questions like "when to use what and how".
> There is so many features just for an Airavata experiment launch which we
> have implemented because of user requirements which we cannot expect users
> to be intuitive enough to figure-out the importance of using them when, why
> and how.
> 
> 
>> Thanks
>> Amila
>> 
>> 
>> On Thu, Jan 30, 2014 at 11:54 PM, Saminda Wijeratne <samindaw@gmail.com
>>> wrote:
>> 
>>> I'm thinking of the reasons why we are having trouble getting a proper
>> API
>>> to work smoothly is that,
>>> 
>>> 
>>>   1. We are trying too hard to generalize when its probably not possible
>>>   to do
>>>   2. When we keep trying to see the big picture we miss the little
>> things
>>>   in the gateways that makes the usage of the API easy or hard for the
>>>   developer.
>>> 
>>> eg: Not all gateways look at "Experiment Launch" use case as passing an
>>> application name and its input to launch the experiment. (I think we've
>>> came across many variations for this use case)
>>> 
>>>   - the inputs could be in different form (could be actual files) or
>> just
>>>   optional
>>>   - application name could be just a reference to a parameter of a
>> global
>>>   application
>>>   - part of the launch process may have runtime dependencies which
>> gateway
>>>   requires to participate
>>>   - the gateway might want more control over the launch configurations
>> at
>>>   runtime.
>>>   - ...
>>> 
>>> I think devs see it as a mismatch of the API for their gateway which
>>> discourages the effort to use the API.
>>> 
>>> IMO part of our Thrift API effort should be to document these with the
>>> solutions similar to Java Patterns.
>>> 
>>> In short, instead of trying to come up with a general API to make
>> everyone
>>> happy we provide solution patterns for a gateway use case which will have
>>> multiple variations. (solution pattern would be use of the API +
>> supporting
>>> code which handles the variation)
>>> 
>>> wdyt?
>>> 
>>> 
>>> Regards,
>>> 
>>> Saminda
>>> 
>> 


Re: Documenting Airavata API usage patterns

Posted by Saminda Wijeratne <sa...@gmail.com>.
On Thu, Jan 30, 2014 at 9:34 PM, Amila Jayasekara
<th...@gmail.com>wrote:

> We definitely need sample code which demonstrate the use of Airavata API.
> But I am not sure whether to call them patterns or API documentation.
>
Its definitely not API documentation. We so far have solve several gateway
problems using Airavata and and each is different on its own although the
ultimate goal was the same. I just think that it would be very useful to
have these variations documented. I used the word "pattern" because even
with different variations there will be other gateways which may be
following the same variation. Thus the word "pattern".

>
> We do not need to create a "very" generic API but the API should be
> intuitive enough for a person with high-level picture in mind to understand
> and guess which functions to call to get something done.
>
In my experience these days most developers google for
examples/solutions/algorithms (atleast to get an idea how to do something)
rather than go through API documentations and designing and implementing
from scratch. And the Airavata API (Thrift version or otherwise) inherits a
context of usage which pops the questions like "when to use what and how".
There is so many features just for an Airavata experiment launch which we
have implemented because of user requirements which we cannot expect users
to be intuitive enough to figure-out the importance of using them when, why
and how.


> Thanks
> Amila
>
>
> On Thu, Jan 30, 2014 at 11:54 PM, Saminda Wijeratne <samindaw@gmail.com
> >wrote:
>
> > I'm thinking of the reasons why we are having trouble getting a proper
> API
> > to work smoothly is that,
> >
> >
> >    1. We are trying too hard to generalize when its probably not possible
> >    to do
> >    2. When we keep trying to see the big picture we miss the little
> things
> >    in the gateways that makes the usage of the API easy or hard for the
> >    developer.
> >
> > eg: Not all gateways look at "Experiment Launch" use case as passing an
> > application name and its input to launch the experiment. (I think we've
> > came across many variations for this use case)
> >
> >    - the inputs could be in different form (could be actual files) or
> just
> >    optional
> >    - application name could be just a reference to a parameter of a
> global
> >    application
> >    - part of the launch process may have runtime dependencies which
> gateway
> >    requires to participate
> >    - the gateway might want more control over the launch configurations
> at
> >    runtime.
> >    - ...
> >
> > I think devs see it as a mismatch of the API for their gateway which
> > discourages the effort to use the API.
> >
> > IMO part of our Thrift API effort should be to document these with the
> > solutions similar to Java Patterns.
> >
> > In short, instead of trying to come up with a general API to make
> everyone
> > happy we provide solution patterns for a gateway use case which will have
> > multiple variations. (solution pattern would be use of the API +
> supporting
> > code which handles the variation)
> >
> > wdyt?
> >
> >
> > Regards,
> >
> > Saminda
> >
>

Re: Documenting Airavata API usage patterns

Posted by Amila Jayasekara <th...@gmail.com>.
We definitely need sample code which demonstrate the use of Airavata API.
But I am not sure whether to call them patterns or API documentation.

We do not need to create a "very" generic API but the API should be
intuitive enough for a person with high-level picture in mind to understand
and guess which functions to call to get something done.

Thanks
Amila


On Thu, Jan 30, 2014 at 11:54 PM, Saminda Wijeratne <sa...@gmail.com>wrote:

> I'm thinking of the reasons why we are having trouble getting a proper API
> to work smoothly is that,
>
>
>    1. We are trying too hard to generalize when its probably not possible
>    to do
>    2. When we keep trying to see the big picture we miss the little things
>    in the gateways that makes the usage of the API easy or hard for the
>    developer.
>
> eg: Not all gateways look at "Experiment Launch" use case as passing an
> application name and its input to launch the experiment. (I think we've
> came across many variations for this use case)
>
>    - the inputs could be in different form (could be actual files) or just
>    optional
>    - application name could be just a reference to a parameter of a global
>    application
>    - part of the launch process may have runtime dependencies which gateway
>    requires to participate
>    - the gateway might want more control over the launch configurations at
>    runtime.
>    - ...
>
> I think devs see it as a mismatch of the API for their gateway which
> discourages the effort to use the API.
>
> IMO part of our Thrift API effort should be to document these with the
> solutions similar to Java Patterns.
>
> In short, instead of trying to come up with a general API to make everyone
> happy we provide solution patterns for a gateway use case which will have
> multiple variations. (solution pattern would be use of the API + supporting
> code which handles the variation)
>
> wdyt?
>
>
> Regards,
>
> Saminda
>