Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hello everyone,

Trust that you're doing great and congratulations to our recently selected
GSoC 2018 students.

As you may have observed from Gitbox notifications, I have used the MockMvc
flavour of Spring Rest Docs <https://projects.spring.io/spring-restdocs/> to
document the APIs for most Fineract CN domain services viz identity,
office, customer, group, accounting, deposit, payroll and teller, created
and merged pull requests. There were failing tests in portfolio ( as I
earlier highlighted last week on the list ) and so snippets weren't
generated to be used for documentation.

After updating the affected repositories, you can view the documentation
for each of the services by opening the
service/src/doc/html5/html5/api-docs.html file.

I happily await your feedback and enhancements.

At Your Service,
Isaac Kamga.

Re: Apache Fineract CN API Documentation

[Myrle Krantz <my...@apache.org>]

On Mon, May 28, 2018 at 12:47 PM, Isaac Kamga <is...@mifos.org> wrote:
>
> I've pushed changes to the *PoCFromIsaac* branch of fineract-cn-customer
> <https://github.com/Izakey/fineract-cn-customer/tree/PocFromIsaac>  for
> review.

Thank you.  This is so much easier than guessing.

>> Currently my guess is that you are setting the token in the token
>> header, but not setting the user or the tenant.  But without the code
>> to look at this is very difficult to determine.

I was right: you're only adding the token, but not the user name or the tenant.

Here's how the tenant is added for feign calls:
https://github.com/Izakey/fineract-cn-api/blob/develop/src/main/java/org/apache/fineract/cn/api/util/TenantedTargetInterceptor.java

And here's how the user and the token are added for feign calls:
https://github.com/Izakey/fineract-cn-api/blob/develop/src/main/java/org/apache/fineract/cn/api/util/TokenedTargetInterceptor.java

But I can only find this line for your MVC calls:
https://github.com/Izakey/fineract-cn-customer/blob/PocFromIsaac/component-test/src/main/java/org/apache/fineract/cn/customer/AuthHelper.java
> requestPostProcessor.addHeader(ApiConstants.AUTHORIZATION_HEADER, UserContextHolder.checkedGetAccessToken());

This only adds the token, but not the user or the tenant.

Best Regards,
Myrle

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hi Myrle,

Thanks for your prompt reply.

On Sat, May 26, 2018 at 11:59 AM, Myrle Krantz <my...@apache.org> wrote:

> Hey Isaac,
>
> There is an artifact test in anubis for acquiring access tokens for
> test.  The tokens for test give permissions to every endpoint in the
> service under test.  In a real environment, the tokens would be
> acquired from the identity environment and would have a much more
> limited set of permissions depending on the role assigned to the user
> being logged in.  Assuming you use anubis.test correctly, you don't
> actually need to validate the token before passing it in, but if
> you're having failures, it makes sense to do so as an aid in debugging
> the problem.


> The Spring Security filter is complex, and requires a deep
> understanding of spring security.  But I believe you can accomplish
> this task without understanding Spring Security.  If you want a better
> understanding of it though, check out this document:
> https://spring.io/guides/topicals/spring-security-architecture/
>
> Can you please push your code somewhere that I can look at it?  It
> would make it much easier to help you.  Two possibilities:
> * push it to your public github repository
> * create a branch in the fineract repos and push it there.
>

I've pushed changes to the *PoCFromIsaac* branch of fineract-cn-customer
<https://github.com/Izakey/fineract-cn-customer/tree/PocFromIsaac>  for
review.


> Currently my guess is that you are setting the token in the token
> header, but not setting the user or the tenant.  But without the code
> to look at this is very difficult to determine.
>
> Best Regards,
> Myrle
>

At Your Service,
Isaac Kamga.


>
> On Thu, May 24, 2018 at 3:00 PM, Isaac Kamga <is...@mifos.org>
> wrote:
> > Hello Myrle,
> >
> > Trust that you're doing great.
> >
> > Following your recommendations, I intended solving the issue using a
> 3-step
> > approach;
> >
> > 1. Obtain token
> > 2. Validate token
> > 3. Add token to MockMvc call as a header.
> >
> > However, I've been unable to get status different from 404 (Not Found)
> and
> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
> one
> > of the 3 steps above wrong.
> >
> > Regarding 1.), I used TenantApplicationSecurityTestRule's
> > getPermissionToken() method to obtain some tokens based on Allowed
> > operations (Read, Change and Delete) and they were each of the form
> "*Bearer
> > eyJhbGciOiJSU....*". Which service actually generates tokens ?
> > TenantAccessTokenSerializer
> > in anubis ?
> >
> > Concerning 2.), The tokens I obtained failed the
> > SystemSecurityEnvironment's isValidToken() method.  So how can we
> validate
> > the obtained tokens ?
> >
> > Regarding 3.), I noticed that Spring MVC Test provides an interface
> called
> > the RequestPostProcessor
> > <https://github.com/spring-projects/spring-framework/
> blob/master/spring-test/src/main/java/org/springframework/
> test/web/servlet/request/RequestPostProcessor.java>
> > which
> > can be used to modify a request. I intend to use this to add a valid
> token
> > to each MockMvc call. I wrote a method which modifies a request by
> > adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> > myToken)* and then running each MockMvc call in the unit test with an
> > object of the class holding this method.
> >
> > Also, you mentioned a Spring Security filter which filters requests to
> > endpoints. Where exactly is this filter located ? I've been scouring
> anubis
> > for it to no avail. I'm considering mocking the filter to permit specific
> > tokens or calls go through.
> >
> > Your help will be greatly appreciated.
> >
> > At Your Service,
> > Isaac Kamga.
> >
> > On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org> wrote:
> >
> >> Hey Isaac,
> >>
> >> On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org>
> >> wrote:
> >> > Thanks for your very helpful feedback.
> >>
> >> You're very welcome.  Thank you for taking it so well.
> >>
> >> > Do we have to use a different approach ( possibly the documentation
> >> module
> >> > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE )
> from
> >> > synchronous ones (GET) ? This can be done later but I wanted to know
> your
> >> > thoughts on this.
> >>
> >> Fortunately we do not.  The asynchronous calls will return an
> >> ACCEPTED, and the synchronous calls will return OK.  From the point of
> >> view of the documentation, and of calling them, that's the only
> >> difference.  The asynchronous calls can also return BAD REQUEST for
> >> any invalid values which are fast to check (where the synchronous ones
> >> will return BAD REQUEST for invalid values regardless of how easy they
> >> are to check.)
> >>
> >> The documentation module is still an open question for me.  But not
> >> because of asynchronous vs synchronous calls.
> >>
> >> > Thanks for shedding more light on how this works. When I saw how
> "easy"
> >> it
> >> > was to do API calls, I asked myself how one could get to intercept
> >> > information such as the status of a response. Building a new test
> harness
> >> > that works with mockmvc can be a daunting task. I hope I can count on
> >> your
> >> > help when I run into frustrations.
> >>
> >> I'll do what I can, but I don't know mockmvc.  I've never used it,
> >> partly because of this problem.
> >>
> >> > So far, I created this document
> >> > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> >> +Fineract+CN+API+Documentation>
> >> > to
> >> > help developers generate the asciidoc files themselves from the unit
> >> tests.
> >> > Would you prefer that we put this in the repository's README file or
> >> leave
> >> > it on confluence ?
> >>
> >> Let's start off with it where it is, and see whether it works by
> >> trying it out there.
> >>
> >> You're doing good,
> >>
> >> Best Regards,
> >> Myrle
> >>
>

Re: Apache Fineract CN API Documentation

[Myrle Krantz <my...@apache.org>]

Hey Isaac,

There is an artifact test in anubis for acquiring access tokens for
test.  The tokens for test give permissions to every endpoint in the
service under test.  In a real environment, the tokens would be
acquired from the identity environment and would have a much more
limited set of permissions depending on the role assigned to the user
being logged in.  Assuming you use anubis.test correctly, you don't
actually need to validate the token before passing it in, but if
you're having failures, it makes sense to do so as an aid in debugging
the problem.

The Spring Security filter is complex, and requires a deep
understanding of spring security.  But I believe you can accomplish
this task without understanding Spring Security.  If you want a better
understanding of it though, check out this document:
https://spring.io/guides/topicals/spring-security-architecture/

Can you please push your code somewhere that I can look at it?  It
would make it much easier to help you.  Two possibilities:
* push it to your public github repository
* create a branch in the fineract repos and push it there.

Currently my guess is that you are setting the token in the token
header, but not setting the user or the tenant.  But without the code
to look at this is very difficult to determine.

Best Regards,
Myrle

On Thu, May 24, 2018 at 3:00 PM, Isaac Kamga <is...@mifos.org> wrote:
> Hello Myrle,
>
> Trust that you're doing great.
>
> Following your recommendations, I intended solving the issue using a 3-step
> approach;
>
> 1. Obtain token
> 2. Validate token
> 3. Add token to MockMvc call as a header.
>
> However, I've been unable to get status different from 404 (Not Found) and
> 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least one
> of the 3 steps above wrong.
>
> Regarding 1.), I used TenantApplicationSecurityTestRule's
> getPermissionToken() method to obtain some tokens based on Allowed
> operations (Read, Change and Delete) and they were each of the form "*Bearer
> eyJhbGciOiJSU....*". Which service actually generates tokens ?
> TenantAccessTokenSerializer
> in anubis ?
>
> Concerning 2.), The tokens I obtained failed the
> SystemSecurityEnvironment's isValidToken() method.  So how can we validate
> the obtained tokens ?
>
> Regarding 3.), I noticed that Spring MVC Test provides an interface called
> the RequestPostProcessor
> <https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java>
> which
> can be used to modify a request. I intend to use this to add a valid token
> to each MockMvc call. I wrote a method which modifies a request by
> adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> myToken)* and then running each MockMvc call in the unit test with an
> object of the class holding this method.
>
> Also, you mentioned a Spring Security filter which filters requests to
> endpoints. Where exactly is this filter located ? I've been scouring anubis
> for it to no avail. I'm considering mocking the filter to permit specific
> tokens or calls go through.
>
> Your help will be greatly appreciated.
>
> At Your Service,
> Isaac Kamga.
>
> On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org> wrote:
>
>> Hey Isaac,
>>
>> On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org>
>> wrote:
>> > Thanks for your very helpful feedback.
>>
>> You're very welcome.  Thank you for taking it so well.
>>
>> > Do we have to use a different approach ( possibly the documentation
>> module
>> > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE ) from
>> > synchronous ones (GET) ? This can be done later but I wanted to know your
>> > thoughts on this.
>>
>> Fortunately we do not.  The asynchronous calls will return an
>> ACCEPTED, and the synchronous calls will return OK.  From the point of
>> view of the documentation, and of calling them, that's the only
>> difference.  The asynchronous calls can also return BAD REQUEST for
>> any invalid values which are fast to check (where the synchronous ones
>> will return BAD REQUEST for invalid values regardless of how easy they
>> are to check.)
>>
>> The documentation module is still an open question for me.  But not
>> because of asynchronous vs synchronous calls.
>>
>> > Thanks for shedding more light on how this works. When I saw how "easy"
>> it
>> > was to do API calls, I asked myself how one could get to intercept
>> > information such as the status of a response. Building a new test harness
>> > that works with mockmvc can be a daunting task. I hope I can count on
>> your
>> > help when I run into frustrations.
>>
>> I'll do what I can, but I don't know mockmvc.  I've never used it,
>> partly because of this problem.
>>
>> > So far, I created this document
>> > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
>> +Fineract+CN+API+Documentation>
>> > to
>> > help developers generate the asciidoc files themselves from the unit
>> tests.
>> > Would you prefer that we put this in the repository's README file or
>> leave
>> > it on confluence ?
>>
>> Let's start off with it where it is, and see whether it works by
>> trying it out there.
>>
>> You're doing good,
>>
>> Best Regards,
>> Myrle
>>

Re: Apache Fineract CN API Documentation

[James Dailey <ja...@gmail.com>]

Hi Isaac -

This content you developed and hosted at <
http://smartfinance.tech/fineract-cn-api-docs/> is visual and useful.  So
that we continue to bring things into the right project locations, I want
to ask the question about how one is supposed to discover, reuse,
contribute to, and consume for ongoing projects.  Does this belong on the
Apache Fineract cwiki site?   Or, is there a reason to have it externally?

I really like the ease of understanding that you are going for.

James

On Fri, Jul 6, 2018 at 10:20 AM Ebenezer Graham <eg...@alustudent.com>
wrote:

> Thank you so much, Isaac.
>
> This documentation will make life much easier.
>
> Will there be documentation for the portfolio service anytime soon?
>
> *At your service,*
>
> *Ebenezer Graham*
>
> *BSc (Hons) Computing*
>
>
> [image: EmailSignature.png]
>
> African Leadership University,
>
> Power Mill Road, Pamplemousses,
>
> Mauritius.
>
>
> ​
> *skype*:
> ​ebenezer.graham
> GitHub <https://github.com/ebenezergraham> | LinkedIn
> <https://www.linkedin.com/in/ebenezer-graham/> | Twitter
> <https://twitter.com/pactmart> | Facebook
> <https://www.facebook.com/pactmart>
> www.pactmart.com | Freelancing made easy.
>
>
> *“Talk is cheap, show me the code.” *- *Linus Torvalds*
>
>
>
> On 5 July 2018 at 19:26, Isaac Kamga <is...@mifos.org> wrote:
>
> > Hello there,
> >
> > Trust that this email finds you in good health.
> >
> > I just hosted the Apache Fineract CN API documentation
> > <http://smartfinance.tech/fineract-cn-api-docs/> which I've been working
> > on
> > so Fineracters can view and give some feedback. This will be quite
> helpful
> > for GSoC students and developers working with Fineract CN as well as
> > business persons who want a feel of the API Documentation. Note that this
> > is just a temporary site for these docs, they'll eventually be hosted on
> > Apache infrastructure.
> >
> > @Myrle Kindly take some time to review the aforementioned Pull Request so
> > we make progress on that front.
> >
> > I hope this helps.
> >
> > At Your Service,
> > Isaac Kamga.
> >
> > On Thu, Jun 28, 2018 at 11:21 AM Isaac Kamga <is...@mifos.org>
> > wrote:
> >
> > > Hi James,
> > >
> > > Thanks for your email.
> > >
> > > Yes, I think the API documentation can be an important part of the
> Apache
> > > Fineract CN project.
> > >
> > > The document
> > > <https://cwiki.apache.org/confluence/display/FINERACT/
> > Apache+Fineract+CN+API+Documentation>
> > > I wrote which you quoted above helps anyone generate the snippets and
> > view
> > > the api docs...developers would be okay with it.
> > > When I'm done with another iteration of the project, I'll update the
> > > community on how the documentation actually looks.
> > >
> > > At Your Service,
> > > Isaac Kamga.
> > >
> > > On Fri, May 25, 2018 at 10:42 PM James Dailey <ja...@gmail.com>
> > > wrote:
> > >
> > >> Isaac - This is a thread I am trying to follow.  Thank you for all the
> > >> work
> > >> you're putting in, and to Myrle for being a mentor on this work.
> Seems
> > >> like it is leading to something really important for the project.
> > >>
> > >> I wonder if this <
> > >>
> > >> https://cwiki.apache.org/confluence/display/FINERACT/
> > Apache+Fineract+CN+API+Documentation
> > >> >
> > >> should or could be expanded to explain and document the API or if we
> > >> should
> > >> have a separate API Documentation File.
> > >>
> > >> At a requirements level, I'm trying to figure out how Mojaloop APIs
> and
> > >> Fineract-CN APIs would interact, perhaps as a model for how
> Fineract-CN
> > >> and
> > >> other outside API driven systems will function together.  On the
> > Mojaloop
> > >> project they have a 190 page documentation of the standard API
> starting
> > >> with some statements that I think may also be relevant to how the
> > >> Fineract-CN services architecture is set up.
> > >>
> > >> https://github.com/mojaloop/mojaloop-specification/blob/
> > master/API%20Definition%20v1.0.pdf
> > >>
> > >>
> > >> Specifically, I'm referring to section 3.1.1. .  Of those
> > characteristics
> > >> mentioned, which apply to Fineract-CN? :
> > >>
> > >>    - Fully Asychronous (esp for long running processes) :  my guess,
> > seems
> > >>    likely yes on Fineract-CN - yes?
> > >>    - Decentralized (no central authority):  My current understanding
> is
> > >>    that Fineract-CN has dependencies but not centralization?
> > >>    - Service Oriented :  that seems like a given in Fineract-CN as it
> is
> > >>    also a micro-services arch.
> > >>    - Not fully stateless (some info required to be kept client and
> > server
> > >>    side to complete fin tranx):  Hmm...
> > >>    - Client (side) decided common ID (complexity reduced by relying on
> > >>    client to initiate tranx calls):  Maybe not yet in our thinking ?
> > >> contrary?
> > >>
> > >> Similarly, there is a reference to how generic URI's are formed with a
> > >> given example:
> > >> scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
> > >>
> > >> and other things like max header size and so forth.
> > >>
> > >> As I lack the skills to actually work on this code, I'm hoping I can
> > >> contribute at the level of conceptual understanding and requirements,
> > and
> > >> perhaps add to the Documentation if I can understand what is actually
> > >> going
> > >> on here.  If this is already documented, please send me there.
> > >>
> > >> ( Myrle - hope this is helpful, if not, let me know please.  )
> > >>
> > >> Thanks,
> > >> - James
> > >>
> > >>
> > >> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
> > >> wrote:
> > >>
> > >> > Hello Myrle,
> > >> >
> > >> > Trust that you're doing great.
> > >> >
> > >> > Following your recommendations, I intended solving the issue using a
> > >> 3-step
> > >> > approach;
> > >> >
> > >> > 1. Obtain token
> > >> > 2. Validate token
> > >> > 3. Add token to MockMvc call as a header.
> > >> >
> > >> > However, I've been unable to get status different from 404 (Not
> Found)
> > >> and
> > >> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at
> least
> > >> one
> > >> > of the 3 steps above wrong.
> > >> >
> > >> > Regarding 1.), I used TenantApplicationSecurityTestRule's
> > >> > getPermissionToken() method to obtain some tokens based on Allowed
> > >> > operations (Read, Change and Delete) and they were each of the form
> > >> > "*Bearer
> > >> > eyJhbGciOiJSU....*". Which service actually generates tokens ?
> > >> > TenantAccessTokenSerializer
> > >> > in anubis ?
> > >> >
> > >> > Concerning 2.), The tokens I obtained failed the
> > >> > SystemSecurityEnvironment's isValidToken() method.  So how can we
> > >> validate
> > >> > the obtained tokens ?
> > >> >
> > >> > Regarding 3.), I noticed that Spring MVC Test provides an interface
> > >> called
> > >> > the RequestPostProcessor
> > >> > <
> > >> >
> > >> https://github.com/spring-projects/spring-framework/
> > blob/master/spring-test/src/main/java/org/springframework/
> > test/web/servlet/request/RequestPostProcessor.java
> > >> > >
> > >> > which
> > >> > can be used to modify a request. I intend to use this to add a valid
> > >> token
> > >> > to each MockMvc call. I wrote a method which modifies a request by
> > >> > adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> > >> > myToken)* and then running each MockMvc call in the unit test with
> an
> > >> > object of the class holding this method.
> > >> >
> > >> > Also, you mentioned a Spring Security filter which filters requests
> to
> > >> > endpoints. Where exactly is this filter located ? I've been scouring
> > >> anubis
> > >> > for it to no avail. I'm considering mocking the filter to permit
> > >> specific
> > >> > tokens or calls go through.
> > >> >
> > >> > Your help will be greatly appreciated.
> > >> >
> > >> > At Your Service,
> > >> > Isaac Kamga.
> > >> >
> > >> > On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org>
> > wrote:
> > >> >
> > >> > > Hey Isaac,
> > >> > >
> > >> > > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <
> isaac.kamga@mifos.org
> > >
> > >> > > wrote:
> > >> > > > Thanks for your very helpful feedback.
> > >> > >
> > >> > > You're very welcome.  Thank you for taking it so well.
> > >> > >
> > >> > > > Do we have to use a different approach ( possibly the
> > documentation
> > >> > > module
> > >> > > > you earlier proposed ) for asynchronous calls (POST, PUT,
> DELETE )
> > >> from
> > >> > > > synchronous ones (GET) ? This can be done later but I wanted to
> > know
> > >> > your
> > >> > > > thoughts on this.
> > >> > >
> > >> > > Fortunately we do not.  The asynchronous calls will return an
> > >> > > ACCEPTED, and the synchronous calls will return OK.  From the
> point
> > of
> > >> > > view of the documentation, and of calling them, that's the only
> > >> > > difference.  The asynchronous calls can also return BAD REQUEST
> for
> > >> > > any invalid values which are fast to check (where the synchronous
> > ones
> > >> > > will return BAD REQUEST for invalid values regardless of how easy
> > they
> > >> > > are to check.)
> > >> > >
> > >> > > The documentation module is still an open question for me.  But
> not
> > >> > > because of asynchronous vs synchronous calls.
> > >> > >
> > >> > > > Thanks for shedding more light on how this works. When I saw how
> > >> "easy"
> > >> > > it
> > >> > > > was to do API calls, I asked myself how one could get to
> intercept
> > >> > > > information such as the status of a response. Building a new
> test
> > >> > harness
> > >> > > > that works with mockmvc can be a daunting task. I hope I can
> count
> > >> on
> > >> > > your
> > >> > > > help when I run into frustrations.
> > >> > >
> > >> > > I'll do what I can, but I don't know mockmvc.  I've never used it,
> > >> > > partly because of this problem.
> > >> > >
> > >> > > > So far, I created this document
> > >> > > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> > >> > > +Fineract+CN+API+Documentation>
> > >> > > > to
> > >> > > > help developers generate the asciidoc files themselves from the
> > unit
> > >> > > tests.
> > >> > > > Would you prefer that we put this in the repository's README
> file
> > or
> > >> > > leave
> > >> > > > it on confluence ?
> > >> > >
> > >> > > Let's start off with it where it is, and see whether it works by
> > >> > > trying it out there.
> > >> > >
> > >> > > You're doing good,
> > >> > >
> > >> > > Best Regards,
> > >> > > Myrle
> > >> > >
> > >> >
> > >>
> > >
> >
>

Re: Apache Fineract CN API Documentation

[Ebenezer Graham <eg...@alustudent.com>]

Thank you so much, Isaac.

This documentation will make life much easier.

Will there be documentation for the portfolio service anytime soon?

*At your service,*

*Ebenezer Graham*

*BSc (Hons) Computing*


[image: EmailSignature.png]

African Leadership University,

Power Mill Road, Pamplemousses,

Mauritius.


​
*skype*:
​ebenezer.graham
GitHub <https://github.com/ebenezergraham> | LinkedIn
<https://www.linkedin.com/in/ebenezer-graham/> | Twitter
<https://twitter.com/pactmart> | Facebook
<https://www.facebook.com/pactmart>
www.pactmart.com | Freelancing made easy.


*“Talk is cheap, show me the code.” *- *Linus Torvalds*



On 5 July 2018 at 19:26, Isaac Kamga <is...@mifos.org> wrote:

> Hello there,
>
> Trust that this email finds you in good health.
>
> I just hosted the Apache Fineract CN API documentation
> <http://smartfinance.tech/fineract-cn-api-docs/> which I've been working
> on
> so Fineracters can view and give some feedback. This will be quite helpful
> for GSoC students and developers working with Fineract CN as well as
> business persons who want a feel of the API Documentation. Note that this
> is just a temporary site for these docs, they'll eventually be hosted on
> Apache infrastructure.
>
> @Myrle Kindly take some time to review the aforementioned Pull Request so
> we make progress on that front.
>
> I hope this helps.
>
> At Your Service,
> Isaac Kamga.
>
> On Thu, Jun 28, 2018 at 11:21 AM Isaac Kamga <is...@mifos.org>
> wrote:
>
> > Hi James,
> >
> > Thanks for your email.
> >
> > Yes, I think the API documentation can be an important part of the Apache
> > Fineract CN project.
> >
> > The document
> > <https://cwiki.apache.org/confluence/display/FINERACT/
> Apache+Fineract+CN+API+Documentation>
> > I wrote which you quoted above helps anyone generate the snippets and
> view
> > the api docs...developers would be okay with it.
> > When I'm done with another iteration of the project, I'll update the
> > community on how the documentation actually looks.
> >
> > At Your Service,
> > Isaac Kamga.
> >
> > On Fri, May 25, 2018 at 10:42 PM James Dailey <ja...@gmail.com>
> > wrote:
> >
> >> Isaac - This is a thread I am trying to follow.  Thank you for all the
> >> work
> >> you're putting in, and to Myrle for being a mentor on this work.  Seems
> >> like it is leading to something really important for the project.
> >>
> >> I wonder if this <
> >>
> >> https://cwiki.apache.org/confluence/display/FINERACT/
> Apache+Fineract+CN+API+Documentation
> >> >
> >> should or could be expanded to explain and document the API or if we
> >> should
> >> have a separate API Documentation File.
> >>
> >> At a requirements level, I'm trying to figure out how Mojaloop APIs and
> >> Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN
> >> and
> >> other outside API driven systems will function together.  On the
> Mojaloop
> >> project they have a 190 page documentation of the standard API starting
> >> with some statements that I think may also be relevant to how the
> >> Fineract-CN services architecture is set up.
> >>
> >> https://github.com/mojaloop/mojaloop-specification/blob/
> master/API%20Definition%20v1.0.pdf
> >>
> >>
> >> Specifically, I'm referring to section 3.1.1. .  Of those
> characteristics
> >> mentioned, which apply to Fineract-CN? :
> >>
> >>    - Fully Asychronous (esp for long running processes) :  my guess,
> seems
> >>    likely yes on Fineract-CN - yes?
> >>    - Decentralized (no central authority):  My current understanding is
> >>    that Fineract-CN has dependencies but not centralization?
> >>    - Service Oriented :  that seems like a given in Fineract-CN as it is
> >>    also a micro-services arch.
> >>    - Not fully stateless (some info required to be kept client and
> server
> >>    side to complete fin tranx):  Hmm...
> >>    - Client (side) decided common ID (complexity reduced by relying on
> >>    client to initiate tranx calls):  Maybe not yet in our thinking ?
> >> contrary?
> >>
> >> Similarly, there is a reference to how generic URI's are formed with a
> >> given example:
> >> scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
> >>
> >> and other things like max header size and so forth.
> >>
> >> As I lack the skills to actually work on this code, I'm hoping I can
> >> contribute at the level of conceptual understanding and requirements,
> and
> >> perhaps add to the Documentation if I can understand what is actually
> >> going
> >> on here.  If this is already documented, please send me there.
> >>
> >> ( Myrle - hope this is helpful, if not, let me know please.  )
> >>
> >> Thanks,
> >> - James
> >>
> >>
> >> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
> >> wrote:
> >>
> >> > Hello Myrle,
> >> >
> >> > Trust that you're doing great.
> >> >
> >> > Following your recommendations, I intended solving the issue using a
> >> 3-step
> >> > approach;
> >> >
> >> > 1. Obtain token
> >> > 2. Validate token
> >> > 3. Add token to MockMvc call as a header.
> >> >
> >> > However, I've been unable to get status different from 404 (Not Found)
> >> and
> >> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
> >> one
> >> > of the 3 steps above wrong.
> >> >
> >> > Regarding 1.), I used TenantApplicationSecurityTestRule's
> >> > getPermissionToken() method to obtain some tokens based on Allowed
> >> > operations (Read, Change and Delete) and they were each of the form
> >> > "*Bearer
> >> > eyJhbGciOiJSU....*". Which service actually generates tokens ?
> >> > TenantAccessTokenSerializer
> >> > in anubis ?
> >> >
> >> > Concerning 2.), The tokens I obtained failed the
> >> > SystemSecurityEnvironment's isValidToken() method.  So how can we
> >> validate
> >> > the obtained tokens ?
> >> >
> >> > Regarding 3.), I noticed that Spring MVC Test provides an interface
> >> called
> >> > the RequestPostProcessor
> >> > <
> >> >
> >> https://github.com/spring-projects/spring-framework/
> blob/master/spring-test/src/main/java/org/springframework/
> test/web/servlet/request/RequestPostProcessor.java
> >> > >
> >> > which
> >> > can be used to modify a request. I intend to use this to add a valid
> >> token
> >> > to each MockMvc call. I wrote a method which modifies a request by
> >> > adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> >> > myToken)* and then running each MockMvc call in the unit test with an
> >> > object of the class holding this method.
> >> >
> >> > Also, you mentioned a Spring Security filter which filters requests to
> >> > endpoints. Where exactly is this filter located ? I've been scouring
> >> anubis
> >> > for it to no avail. I'm considering mocking the filter to permit
> >> specific
> >> > tokens or calls go through.
> >> >
> >> > Your help will be greatly appreciated.
> >> >
> >> > At Your Service,
> >> > Isaac Kamga.
> >> >
> >> > On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org>
> wrote:
> >> >
> >> > > Hey Isaac,
> >> > >
> >> > > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <isaac.kamga@mifos.org
> >
> >> > > wrote:
> >> > > > Thanks for your very helpful feedback.
> >> > >
> >> > > You're very welcome.  Thank you for taking it so well.
> >> > >
> >> > > > Do we have to use a different approach ( possibly the
> documentation
> >> > > module
> >> > > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE )
> >> from
> >> > > > synchronous ones (GET) ? This can be done later but I wanted to
> know
> >> > your
> >> > > > thoughts on this.
> >> > >
> >> > > Fortunately we do not.  The asynchronous calls will return an
> >> > > ACCEPTED, and the synchronous calls will return OK.  From the point
> of
> >> > > view of the documentation, and of calling them, that's the only
> >> > > difference.  The asynchronous calls can also return BAD REQUEST for
> >> > > any invalid values which are fast to check (where the synchronous
> ones
> >> > > will return BAD REQUEST for invalid values regardless of how easy
> they
> >> > > are to check.)
> >> > >
> >> > > The documentation module is still an open question for me.  But not
> >> > > because of asynchronous vs synchronous calls.
> >> > >
> >> > > > Thanks for shedding more light on how this works. When I saw how
> >> "easy"
> >> > > it
> >> > > > was to do API calls, I asked myself how one could get to intercept
> >> > > > information such as the status of a response. Building a new test
> >> > harness
> >> > > > that works with mockmvc can be a daunting task. I hope I can count
> >> on
> >> > > your
> >> > > > help when I run into frustrations.
> >> > >
> >> > > I'll do what I can, but I don't know mockmvc.  I've never used it,
> >> > > partly because of this problem.
> >> > >
> >> > > > So far, I created this document
> >> > > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> >> > > +Fineract+CN+API+Documentation>
> >> > > > to
> >> > > > help developers generate the asciidoc files themselves from the
> unit
> >> > > tests.
> >> > > > Would you prefer that we put this in the repository's README file
> or
> >> > > leave
> >> > > > it on confluence ?
> >> > >
> >> > > Let's start off with it where it is, and see whether it works by
> >> > > trying it out there.
> >> > >
> >> > > You're doing good,
> >> > >
> >> > > Best Regards,
> >> > > Myrle
> >> > >
> >> >
> >>
> >
>

Re: Apache Fineract CN API Documentation

[Ruphine Kengne <ru...@gmail.com>]

Hello Isaac,

Congratulations and thank you for your work done.
I am already getting some help from that API docs to consume some of the
endpoints for the Group Microservice to actually know what data to send in
for a particular endpoint.

It is actually helpful. Thanks

Regards,

Ruphine Kengne

On 5 July 2018 at 16:26, Isaac Kamga <is...@mifos.org> wrote:

> Hello there,
>
> Trust that this email finds you in good health.
>
> I just hosted the Apache Fineract CN API documentation
> <http://smartfinance.tech/fineract-cn-api-docs/> which I've been working
> on
> so Fineracters can view and give some feedback. This will be quite helpful
> for GSoC students and developers working with Fineract CN as well as
> business persons who want a feel of the API Documentation. Note that this
> is just a temporary site for these docs, they'll eventually be hosted on
> Apache infrastructure.
>
> @Myrle Kindly take some time to review the aforementioned Pull Request so
> we make progress on that front.
>
> I hope this helps.
>
> At Your Service,
> Isaac Kamga.
>
> On Thu, Jun 28, 2018 at 11:21 AM Isaac Kamga <is...@mifos.org>
> wrote:
>
> > Hi James,
> >
> > Thanks for your email.
> >
> > Yes, I think the API documentation can be an important part of the Apache
> > Fineract CN project.
> >
> > The document
> > <https://cwiki.apache.org/confluence/display/FINERACT/
> Apache+Fineract+CN+API+Documentation>
> > I wrote which you quoted above helps anyone generate the snippets and
> view
> > the api docs...developers would be okay with it.
> > When I'm done with another iteration of the project, I'll update the
> > community on how the documentation actually looks.
> >
> > At Your Service,
> > Isaac Kamga.
> >
> > On Fri, May 25, 2018 at 10:42 PM James Dailey <ja...@gmail.com>
> > wrote:
> >
> >> Isaac - This is a thread I am trying to follow.  Thank you for all the
> >> work
> >> you're putting in, and to Myrle for being a mentor on this work.  Seems
> >> like it is leading to something really important for the project.
> >>
> >> I wonder if this <
> >>
> >> https://cwiki.apache.org/confluence/display/FINERACT/
> Apache+Fineract+CN+API+Documentation
> >> >
> >> should or could be expanded to explain and document the API or if we
> >> should
> >> have a separate API Documentation File.
> >>
> >> At a requirements level, I'm trying to figure out how Mojaloop APIs and
> >> Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN
> >> and
> >> other outside API driven systems will function together.  On the
> Mojaloop
> >> project they have a 190 page documentation of the standard API starting
> >> with some statements that I think may also be relevant to how the
> >> Fineract-CN services architecture is set up.
> >>
> >> https://github.com/mojaloop/mojaloop-specification/blob/
> master/API%20Definition%20v1.0.pdf
> >>
> >>
> >> Specifically, I'm referring to section 3.1.1. .  Of those
> characteristics
> >> mentioned, which apply to Fineract-CN? :
> >>
> >>    - Fully Asychronous (esp for long running processes) :  my guess,
> seems
> >>    likely yes on Fineract-CN - yes?
> >>    - Decentralized (no central authority):  My current understanding is
> >>    that Fineract-CN has dependencies but not centralization?
> >>    - Service Oriented :  that seems like a given in Fineract-CN as it is
> >>    also a micro-services arch.
> >>    - Not fully stateless (some info required to be kept client and
> server
> >>    side to complete fin tranx):  Hmm...
> >>    - Client (side) decided common ID (complexity reduced by relying on
> >>    client to initiate tranx calls):  Maybe not yet in our thinking ?
> >> contrary?
> >>
> >> Similarly, there is a reference to how generic URI's are formed with a
> >> given example:
> >> scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
> >>
> >> and other things like max header size and so forth.
> >>
> >> As I lack the skills to actually work on this code, I'm hoping I can
> >> contribute at the level of conceptual understanding and requirements,
> and
> >> perhaps add to the Documentation if I can understand what is actually
> >> going
> >> on here.  If this is already documented, please send me there.
> >>
> >> ( Myrle - hope this is helpful, if not, let me know please.  )
> >>
> >> Thanks,
> >> - James
> >>
> >>
> >> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
> >> wrote:
> >>
> >> > Hello Myrle,
> >> >
> >> > Trust that you're doing great.
> >> >
> >> > Following your recommendations, I intended solving the issue using a
> >> 3-step
> >> > approach;
> >> >
> >> > 1. Obtain token
> >> > 2. Validate token
> >> > 3. Add token to MockMvc call as a header.
> >> >
> >> > However, I've been unable to get status different from 404 (Not Found)
> >> and
> >> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
> >> one
> >> > of the 3 steps above wrong.
> >> >
> >> > Regarding 1.), I used TenantApplicationSecurityTestRule's
> >> > getPermissionToken() method to obtain some tokens based on Allowed
> >> > operations (Read, Change and Delete) and they were each of the form
> >> > "*Bearer
> >> > eyJhbGciOiJSU....*". Which service actually generates tokens ?
> >> > TenantAccessTokenSerializer
> >> > in anubis ?
> >> >
> >> > Concerning 2.), The tokens I obtained failed the
> >> > SystemSecurityEnvironment's isValidToken() method.  So how can we
> >> validate
> >> > the obtained tokens ?
> >> >
> >> > Regarding 3.), I noticed that Spring MVC Test provides an interface
> >> called
> >> > the RequestPostProcessor
> >> > <
> >> >
> >> https://github.com/spring-projects/spring-framework/
> blob/master/spring-test/src/main/java/org/springframework/
> test/web/servlet/request/RequestPostProcessor.java
> >> > >
> >> > which
> >> > can be used to modify a request. I intend to use this to add a valid
> >> token
> >> > to each MockMvc call. I wrote a method which modifies a request by
> >> > adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> >> > myToken)* and then running each MockMvc call in the unit test with an
> >> > object of the class holding this method.
> >> >
> >> > Also, you mentioned a Spring Security filter which filters requests to
> >> > endpoints. Where exactly is this filter located ? I've been scouring
> >> anubis
> >> > for it to no avail. I'm considering mocking the filter to permit
> >> specific
> >> > tokens or calls go through.
> >> >
> >> > Your help will be greatly appreciated.
> >> >
> >> > At Your Service,
> >> > Isaac Kamga.
> >> >
> >> > On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org>
> wrote:
> >> >
> >> > > Hey Isaac,
> >> > >
> >> > > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <isaac.kamga@mifos.org
> >
> >> > > wrote:
> >> > > > Thanks for your very helpful feedback.
> >> > >
> >> > > You're very welcome.  Thank you for taking it so well.
> >> > >
> >> > > > Do we have to use a different approach ( possibly the
> documentation
> >> > > module
> >> > > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE )
> >> from
> >> > > > synchronous ones (GET) ? This can be done later but I wanted to
> know
> >> > your
> >> > > > thoughts on this.
> >> > >
> >> > > Fortunately we do not.  The asynchronous calls will return an
> >> > > ACCEPTED, and the synchronous calls will return OK.  From the point
> of
> >> > > view of the documentation, and of calling them, that's the only
> >> > > difference.  The asynchronous calls can also return BAD REQUEST for
> >> > > any invalid values which are fast to check (where the synchronous
> ones
> >> > > will return BAD REQUEST for invalid values regardless of how easy
> they
> >> > > are to check.)
> >> > >
> >> > > The documentation module is still an open question for me.  But not
> >> > > because of asynchronous vs synchronous calls.
> >> > >
> >> > > > Thanks for shedding more light on how this works. When I saw how
> >> "easy"
> >> > > it
> >> > > > was to do API calls, I asked myself how one could get to intercept
> >> > > > information such as the status of a response. Building a new test
> >> > harness
> >> > > > that works with mockmvc can be a daunting task. I hope I can count
> >> on
> >> > > your
> >> > > > help when I run into frustrations.
> >> > >
> >> > > I'll do what I can, but I don't know mockmvc.  I've never used it,
> >> > > partly because of this problem.
> >> > >
> >> > > > So far, I created this document
> >> > > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> >> > > +Fineract+CN+API+Documentation>
> >> > > > to
> >> > > > help developers generate the asciidoc files themselves from the
> unit
> >> > > tests.
> >> > > > Would you prefer that we put this in the repository's README file
> or
> >> > > leave
> >> > > > it on confluence ?
> >> > >
> >> > > Let's start off with it where it is, and see whether it works by
> >> > > trying it out there.
> >> > >
> >> > > You're doing good,
> >> > >
> >> > > Best Regards,
> >> > > Myrle
> >> > >
> >> >
> >>
> >
>

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hello Awasum,

Thanks a million for your kindness.

I have created Pull Requests and sub-tasks to issue FINCN-6
<https://issues.apache.org/jira/browse/FINCN-6> and await your review.

Cheers,
Isaac Kamga.

On Mon, Sep 3, 2018 at 1:41 PM Awasum Yannick <aw...@apache.org> wrote:

> Hello Isaac,
>
> I have merged the PR which documents Customer APIs.
> Follow the code style adjustment and send the rest of the PRs.
> I will be available today to review. From tomorrow, I will be unavailable.
>
> Thanks for your contributions and for being so patient over the pass few
> weeks as many of us were busy.
>
> Thanks.
> Awasum.
>
> On Sat, Aug 18, 2018 at 11:36 AM Awasum Yannick <aw...@apache.org> wrote:
>
> > Hello Myrle, Isaac,
> >
> > What is the status of the API Doc? What is left for this code to be
> > reviewed and merged?
> >
> > This is weekend and I have some time today or tomorrow to help and review
> > if you all are busy. Let me know
> >
> > Thanks.
> > Awasum
> >
> > On Thu, Jul 5, 2018 at 4:26 PM Isaac Kamga <is...@mifos.org>
> wrote:
> >
> >> Hello there,
> >>
> >> Trust that this email finds you in good health.
> >>
> >> I just hosted the Apache Fineract CN API documentation
> >> <http://smartfinance.tech/fineract-cn-api-docs/> which I've been
> working
> >> on
> >> so Fineracters can view and give some feedback. This will be quite
> helpful
> >> for GSoC students and developers working with Fineract CN as well as
> >> business persons who want a feel of the API Documentation. Note that
> this
> >> is just a temporary site for these docs, they'll eventually be hosted on
> >> Apache infrastructure.
> >>
> >> @Myrle Kindly take some time to review the aforementioned Pull Request
> so
> >> we make progress on that front.
> >>
> >> I hope this helps.
> >>
> >> At Your Service,
> >> Isaac Kamga.
> >>
> >> On Thu, Jun 28, 2018 at 11:21 AM Isaac Kamga <is...@mifos.org>
> >> wrote:
> >>
> >> > Hi James,
> >> >
> >> > Thanks for your email.
> >> >
> >> > Yes, I think the API documentation can be an important part of the
> >> Apache
> >> > Fineract CN project.
> >> >
> >> > The document
> >> > <
> >>
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
> >> >
> >> > I wrote which you quoted above helps anyone generate the snippets and
> >> view
> >> > the api docs...developers would be okay with it.
> >> > When I'm done with another iteration of the project, I'll update the
> >> > community on how the documentation actually looks.
> >> >
> >> > At Your Service,
> >> > Isaac Kamga.
> >> >
> >> > On Fri, May 25, 2018 at 10:42 PM James Dailey <jamespdailey@gmail.com
> >
> >> > wrote:
> >> >
> >> >> Isaac - This is a thread I am trying to follow.  Thank you for all
> the
> >> >> work
> >> >> you're putting in, and to Myrle for being a mentor on this work.
> Seems
> >> >> like it is leading to something really important for the project.
> >> >>
> >> >> I wonder if this <
> >> >>
> >> >>
> >>
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
> >> >> >
> >> >> should or could be expanded to explain and document the API or if we
> >> >> should
> >> >> have a separate API Documentation File.
> >> >>
> >> >> At a requirements level, I'm trying to figure out how Mojaloop APIs
> and
> >> >> Fineract-CN APIs would interact, perhaps as a model for how
> Fineract-CN
> >> >> and
> >> >> other outside API driven systems will function together.  On the
> >> Mojaloop
> >> >> project they have a 190 page documentation of the standard API
> starting
> >> >> with some statements that I think may also be relevant to how the
> >> >> Fineract-CN services architecture is set up.
> >> >>
> >> >>
> >>
> https://github.com/mojaloop/mojaloop-specification/blob/master/API%20Definition%20v1.0.pdf
> >> >>
> >> >>
> >> >> Specifically, I'm referring to section 3.1.1. .  Of those
> >> characteristics
> >> >> mentioned, which apply to Fineract-CN? :
> >> >>
> >> >>    - Fully Asychronous (esp for long running processes) :  my guess,
> >> seems
> >> >>    likely yes on Fineract-CN - yes?
> >> >>    - Decentralized (no central authority):  My current understanding
> is
> >> >>    that Fineract-CN has dependencies but not centralization?
> >> >>    - Service Oriented :  that seems like a given in Fineract-CN as it
> >> is
> >> >>    also a micro-services arch.
> >> >>    - Not fully stateless (some info required to be kept client and
> >> server
> >> >>    side to complete fin tranx):  Hmm...
> >> >>    - Client (side) decided common ID (complexity reduced by relying
> on
> >> >>    client to initiate tranx calls):  Maybe not yet in our thinking ?
> >> >> contrary?
> >> >>
> >> >> Similarly, there is a reference to how generic URI's are formed with
> a
> >> >> given example:
> >> >> scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
> >> >>
> >> >> and other things like max header size and so forth.
> >> >>
> >> >> As I lack the skills to actually work on this code, I'm hoping I can
> >> >> contribute at the level of conceptual understanding and requirements,
> >> and
> >> >> perhaps add to the Documentation if I can understand what is actually
> >> >> going
> >> >> on here.  If this is already documented, please send me there.
> >> >>
> >> >> ( Myrle - hope this is helpful, if not, let me know please.  )
> >> >>
> >> >> Thanks,
> >> >> - James
> >> >>
> >> >>
> >> >> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
> >> >> wrote:
> >> >>
> >> >> > Hello Myrle,
> >> >> >
> >> >> > Trust that you're doing great.
> >> >> >
> >> >> > Following your recommendations, I intended solving the issue using
> a
> >> >> 3-step
> >> >> > approach;
> >> >> >
> >> >> > 1. Obtain token
> >> >> > 2. Validate token
> >> >> > 3. Add token to MockMvc call as a header.
> >> >> >
> >> >> > However, I've been unable to get status different from 404 (Not
> >> Found)
> >> >> and
> >> >> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at
> >> least
> >> >> one
> >> >> > of the 3 steps above wrong.
> >> >> >
> >> >> > Regarding 1.), I used TenantApplicationSecurityTestRule's
> >> >> > getPermissionToken() method to obtain some tokens based on Allowed
> >> >> > operations (Read, Change and Delete) and they were each of the form
> >> >> > "*Bearer
> >> >> > eyJhbGciOiJSU....*". Which service actually generates tokens ?
> >> >> > TenantAccessTokenSerializer
> >> >> > in anubis ?
> >> >> >
> >> >> > Concerning 2.), The tokens I obtained failed the
> >> >> > SystemSecurityEnvironment's isValidToken() method.  So how can we
> >> >> validate
> >> >> > the obtained tokens ?
> >> >> >
> >> >> > Regarding 3.), I noticed that Spring MVC Test provides an interface
> >> >> called
> >> >> > the RequestPostProcessor
> >> >> > <
> >> >> >
> >> >>
> >>
> https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java
> >> >> > >
> >> >> > which
> >> >> > can be used to modify a request. I intend to use this to add a
> valid
> >> >> token
> >> >> > to each MockMvc call. I wrote a method which modifies a request by
> >> >> > adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> >> >> > myToken)* and then running each MockMvc call in the unit test with
> an
> >> >> > object of the class holding this method.
> >> >> >
> >> >> > Also, you mentioned a Spring Security filter which filters requests
> >> to
> >> >> > endpoints. Where exactly is this filter located ? I've been
> scouring
> >> >> anubis
> >> >> > for it to no avail. I'm considering mocking the filter to permit
> >> >> specific
> >> >> > tokens or calls go through.
> >> >> >
> >> >> > Your help will be greatly appreciated.
> >> >> >
> >> >> > At Your Service,
> >> >> > Isaac Kamga.
> >> >> >
> >> >> > On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org>
> >> wrote:
> >> >> >
> >> >> > > Hey Isaac,
> >> >> > >
> >> >> > > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <
> >> isaac.kamga@mifos.org>
> >> >> > > wrote:
> >> >> > > > Thanks for your very helpful feedback.
> >> >> > >
> >> >> > > You're very welcome.  Thank you for taking it so well.
> >> >> > >
> >> >> > > > Do we have to use a different approach ( possibly the
> >> documentation
> >> >> > > module
> >> >> > > > you earlier proposed ) for asynchronous calls (POST, PUT,
> DELETE
> >> )
> >> >> from
> >> >> > > > synchronous ones (GET) ? This can be done later but I wanted to
> >> know
> >> >> > your
> >> >> > > > thoughts on this.
> >> >> > >
> >> >> > > Fortunately we do not.  The asynchronous calls will return an
> >> >> > > ACCEPTED, and the synchronous calls will return OK.  From the
> >> point of
> >> >> > > view of the documentation, and of calling them, that's the only
> >> >> > > difference.  The asynchronous calls can also return BAD REQUEST
> for
> >> >> > > any invalid values which are fast to check (where the synchronous
> >> ones
> >> >> > > will return BAD REQUEST for invalid values regardless of how easy
> >> they
> >> >> > > are to check.)
> >> >> > >
> >> >> > > The documentation module is still an open question for me.  But
> not
> >> >> > > because of asynchronous vs synchronous calls.
> >> >> > >
> >> >> > > > Thanks for shedding more light on how this works. When I saw
> how
> >> >> "easy"
> >> >> > > it
> >> >> > > > was to do API calls, I asked myself how one could get to
> >> intercept
> >> >> > > > information such as the status of a response. Building a new
> test
> >> >> > harness
> >> >> > > > that works with mockmvc can be a daunting task. I hope I can
> >> count
> >> >> on
> >> >> > > your
> >> >> > > > help when I run into frustrations.
> >> >> > >
> >> >> > > I'll do what I can, but I don't know mockmvc.  I've never used
> it,
> >> >> > > partly because of this problem.
> >> >> > >
> >> >> > > > So far, I created this document
> >> >> > > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> >> >> > > +Fineract+CN+API+Documentation>
> >> >> > > > to
> >> >> > > > help developers generate the asciidoc files themselves from the
> >> unit
> >> >> > > tests.
> >> >> > > > Would you prefer that we put this in the repository's README
> >> file or
> >> >> > > leave
> >> >> > > > it on confluence ?
> >> >> > >
> >> >> > > Let's start off with it where it is, and see whether it works by
> >> >> > > trying it out there.
> >> >> > >
> >> >> > > You're doing good,
> >> >> > >
> >> >> > > Best Regards,
> >> >> > > Myrle
> >> >> > >
> >> >> >
> >> >>
> >> >
> >>
> >
>

Re: Apache Fineract CN API Documentation

[Awasum Yannick <aw...@apache.org>]

Hello Isaac,

I have merged the PR which documents Customer APIs.
Follow the code style adjustment and send the rest of the PRs.
I will be available today to review. From tomorrow, I will be unavailable.

Thanks for your contributions and for being so patient over the pass few
weeks as many of us were busy.

Thanks.
Awasum.

On Sat, Aug 18, 2018 at 11:36 AM Awasum Yannick <aw...@apache.org> wrote:

> Hello Myrle, Isaac,
>
> What is the status of the API Doc? What is left for this code to be
> reviewed and merged?
>
> This is weekend and I have some time today or tomorrow to help and review
> if you all are busy. Let me know
>
> Thanks.
> Awasum
>
> On Thu, Jul 5, 2018 at 4:26 PM Isaac Kamga <is...@mifos.org> wrote:
>
>> Hello there,
>>
>> Trust that this email finds you in good health.
>>
>> I just hosted the Apache Fineract CN API documentation
>> <http://smartfinance.tech/fineract-cn-api-docs/> which I've been working
>> on
>> so Fineracters can view and give some feedback. This will be quite helpful
>> for GSoC students and developers working with Fineract CN as well as
>> business persons who want a feel of the API Documentation. Note that this
>> is just a temporary site for these docs, they'll eventually be hosted on
>> Apache infrastructure.
>>
>> @Myrle Kindly take some time to review the aforementioned Pull Request so
>> we make progress on that front.
>>
>> I hope this helps.
>>
>> At Your Service,
>> Isaac Kamga.
>>
>> On Thu, Jun 28, 2018 at 11:21 AM Isaac Kamga <is...@mifos.org>
>> wrote:
>>
>> > Hi James,
>> >
>> > Thanks for your email.
>> >
>> > Yes, I think the API documentation can be an important part of the
>> Apache
>> > Fineract CN project.
>> >
>> > The document
>> > <
>> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
>> >
>> > I wrote which you quoted above helps anyone generate the snippets and
>> view
>> > the api docs...developers would be okay with it.
>> > When I'm done with another iteration of the project, I'll update the
>> > community on how the documentation actually looks.
>> >
>> > At Your Service,
>> > Isaac Kamga.
>> >
>> > On Fri, May 25, 2018 at 10:42 PM James Dailey <ja...@gmail.com>
>> > wrote:
>> >
>> >> Isaac - This is a thread I am trying to follow.  Thank you for all the
>> >> work
>> >> you're putting in, and to Myrle for being a mentor on this work.  Seems
>> >> like it is leading to something really important for the project.
>> >>
>> >> I wonder if this <
>> >>
>> >>
>> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
>> >> >
>> >> should or could be expanded to explain and document the API or if we
>> >> should
>> >> have a separate API Documentation File.
>> >>
>> >> At a requirements level, I'm trying to figure out how Mojaloop APIs and
>> >> Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN
>> >> and
>> >> other outside API driven systems will function together.  On the
>> Mojaloop
>> >> project they have a 190 page documentation of the standard API starting
>> >> with some statements that I think may also be relevant to how the
>> >> Fineract-CN services architecture is set up.
>> >>
>> >>
>> https://github.com/mojaloop/mojaloop-specification/blob/master/API%20Definition%20v1.0.pdf
>> >>
>> >>
>> >> Specifically, I'm referring to section 3.1.1. .  Of those
>> characteristics
>> >> mentioned, which apply to Fineract-CN? :
>> >>
>> >>    - Fully Asychronous (esp for long running processes) :  my guess,
>> seems
>> >>    likely yes on Fineract-CN - yes?
>> >>    - Decentralized (no central authority):  My current understanding is
>> >>    that Fineract-CN has dependencies but not centralization?
>> >>    - Service Oriented :  that seems like a given in Fineract-CN as it
>> is
>> >>    also a micro-services arch.
>> >>    - Not fully stateless (some info required to be kept client and
>> server
>> >>    side to complete fin tranx):  Hmm...
>> >>    - Client (side) decided common ID (complexity reduced by relying on
>> >>    client to initiate tranx calls):  Maybe not yet in our thinking ?
>> >> contrary?
>> >>
>> >> Similarly, there is a reference to how generic URI's are formed with a
>> >> given example:
>> >> scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
>> >>
>> >> and other things like max header size and so forth.
>> >>
>> >> As I lack the skills to actually work on this code, I'm hoping I can
>> >> contribute at the level of conceptual understanding and requirements,
>> and
>> >> perhaps add to the Documentation if I can understand what is actually
>> >> going
>> >> on here.  If this is already documented, please send me there.
>> >>
>> >> ( Myrle - hope this is helpful, if not, let me know please.  )
>> >>
>> >> Thanks,
>> >> - James
>> >>
>> >>
>> >> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
>> >> wrote:
>> >>
>> >> > Hello Myrle,
>> >> >
>> >> > Trust that you're doing great.
>> >> >
>> >> > Following your recommendations, I intended solving the issue using a
>> >> 3-step
>> >> > approach;
>> >> >
>> >> > 1. Obtain token
>> >> > 2. Validate token
>> >> > 3. Add token to MockMvc call as a header.
>> >> >
>> >> > However, I've been unable to get status different from 404 (Not
>> Found)
>> >> and
>> >> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at
>> least
>> >> one
>> >> > of the 3 steps above wrong.
>> >> >
>> >> > Regarding 1.), I used TenantApplicationSecurityTestRule's
>> >> > getPermissionToken() method to obtain some tokens based on Allowed
>> >> > operations (Read, Change and Delete) and they were each of the form
>> >> > "*Bearer
>> >> > eyJhbGciOiJSU....*". Which service actually generates tokens ?
>> >> > TenantAccessTokenSerializer
>> >> > in anubis ?
>> >> >
>> >> > Concerning 2.), The tokens I obtained failed the
>> >> > SystemSecurityEnvironment's isValidToken() method.  So how can we
>> >> validate
>> >> > the obtained tokens ?
>> >> >
>> >> > Regarding 3.), I noticed that Spring MVC Test provides an interface
>> >> called
>> >> > the RequestPostProcessor
>> >> > <
>> >> >
>> >>
>> https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java
>> >> > >
>> >> > which
>> >> > can be used to modify a request. I intend to use this to add a valid
>> >> token
>> >> > to each MockMvc call. I wrote a method which modifies a request by
>> >> > adding a *header(ApiConstants.AUTHORIZATON_HEADER,
>> >> > myToken)* and then running each MockMvc call in the unit test with an
>> >> > object of the class holding this method.
>> >> >
>> >> > Also, you mentioned a Spring Security filter which filters requests
>> to
>> >> > endpoints. Where exactly is this filter located ? I've been scouring
>> >> anubis
>> >> > for it to no avail. I'm considering mocking the filter to permit
>> >> specific
>> >> > tokens or calls go through.
>> >> >
>> >> > Your help will be greatly appreciated.
>> >> >
>> >> > At Your Service,
>> >> > Isaac Kamga.
>> >> >
>> >> > On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org>
>> wrote:
>> >> >
>> >> > > Hey Isaac,
>> >> > >
>> >> > > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <
>> isaac.kamga@mifos.org>
>> >> > > wrote:
>> >> > > > Thanks for your very helpful feedback.
>> >> > >
>> >> > > You're very welcome.  Thank you for taking it so well.
>> >> > >
>> >> > > > Do we have to use a different approach ( possibly the
>> documentation
>> >> > > module
>> >> > > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE
>> )
>> >> from
>> >> > > > synchronous ones (GET) ? This can be done later but I wanted to
>> know
>> >> > your
>> >> > > > thoughts on this.
>> >> > >
>> >> > > Fortunately we do not.  The asynchronous calls will return an
>> >> > > ACCEPTED, and the synchronous calls will return OK.  From the
>> point of
>> >> > > view of the documentation, and of calling them, that's the only
>> >> > > difference.  The asynchronous calls can also return BAD REQUEST for
>> >> > > any invalid values which are fast to check (where the synchronous
>> ones
>> >> > > will return BAD REQUEST for invalid values regardless of how easy
>> they
>> >> > > are to check.)
>> >> > >
>> >> > > The documentation module is still an open question for me.  But not
>> >> > > because of asynchronous vs synchronous calls.
>> >> > >
>> >> > > > Thanks for shedding more light on how this works. When I saw how
>> >> "easy"
>> >> > > it
>> >> > > > was to do API calls, I asked myself how one could get to
>> intercept
>> >> > > > information such as the status of a response. Building a new test
>> >> > harness
>> >> > > > that works with mockmvc can be a daunting task. I hope I can
>> count
>> >> on
>> >> > > your
>> >> > > > help when I run into frustrations.
>> >> > >
>> >> > > I'll do what I can, but I don't know mockmvc.  I've never used it,
>> >> > > partly because of this problem.
>> >> > >
>> >> > > > So far, I created this document
>> >> > > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
>> >> > > +Fineract+CN+API+Documentation>
>> >> > > > to
>> >> > > > help developers generate the asciidoc files themselves from the
>> unit
>> >> > > tests.
>> >> > > > Would you prefer that we put this in the repository's README
>> file or
>> >> > > leave
>> >> > > > it on confluence ?
>> >> > >
>> >> > > Let's start off with it where it is, and see whether it works by
>> >> > > trying it out there.
>> >> > >
>> >> > > You're doing good,
>> >> > >
>> >> > > Best Regards,
>> >> > > Myrle
>> >> > >
>> >> >
>> >>
>> >
>>
>

Re: Apache Fineract CN API Documentation

[Awasum Yannick <aw...@apache.org>]

Hello Myrle, Isaac,

What is the status of the API Doc? What is left for this code to be
reviewed and merged?

This is weekend and I have some time today or tomorrow to help and review
if you all are busy. Let me know

Thanks.
Awasum

On Thu, Jul 5, 2018 at 4:26 PM Isaac Kamga <is...@mifos.org> wrote:

> Hello there,
>
> Trust that this email finds you in good health.
>
> I just hosted the Apache Fineract CN API documentation
> <http://smartfinance.tech/fineract-cn-api-docs/> which I've been working
> on
> so Fineracters can view and give some feedback. This will be quite helpful
> for GSoC students and developers working with Fineract CN as well as
> business persons who want a feel of the API Documentation. Note that this
> is just a temporary site for these docs, they'll eventually be hosted on
> Apache infrastructure.
>
> @Myrle Kindly take some time to review the aforementioned Pull Request so
> we make progress on that front.
>
> I hope this helps.
>
> At Your Service,
> Isaac Kamga.
>
> On Thu, Jun 28, 2018 at 11:21 AM Isaac Kamga <is...@mifos.org>
> wrote:
>
> > Hi James,
> >
> > Thanks for your email.
> >
> > Yes, I think the API documentation can be an important part of the Apache
> > Fineract CN project.
> >
> > The document
> > <
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
> >
> > I wrote which you quoted above helps anyone generate the snippets and
> view
> > the api docs...developers would be okay with it.
> > When I'm done with another iteration of the project, I'll update the
> > community on how the documentation actually looks.
> >
> > At Your Service,
> > Isaac Kamga.
> >
> > On Fri, May 25, 2018 at 10:42 PM James Dailey <ja...@gmail.com>
> > wrote:
> >
> >> Isaac - This is a thread I am trying to follow.  Thank you for all the
> >> work
> >> you're putting in, and to Myrle for being a mentor on this work.  Seems
> >> like it is leading to something really important for the project.
> >>
> >> I wonder if this <
> >>
> >>
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
> >> >
> >> should or could be expanded to explain and document the API or if we
> >> should
> >> have a separate API Documentation File.
> >>
> >> At a requirements level, I'm trying to figure out how Mojaloop APIs and
> >> Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN
> >> and
> >> other outside API driven systems will function together.  On the
> Mojaloop
> >> project they have a 190 page documentation of the standard API starting
> >> with some statements that I think may also be relevant to how the
> >> Fineract-CN services architecture is set up.
> >>
> >>
> https://github.com/mojaloop/mojaloop-specification/blob/master/API%20Definition%20v1.0.pdf
> >>
> >>
> >> Specifically, I'm referring to section 3.1.1. .  Of those
> characteristics
> >> mentioned, which apply to Fineract-CN? :
> >>
> >>    - Fully Asychronous (esp for long running processes) :  my guess,
> seems
> >>    likely yes on Fineract-CN - yes?
> >>    - Decentralized (no central authority):  My current understanding is
> >>    that Fineract-CN has dependencies but not centralization?
> >>    - Service Oriented :  that seems like a given in Fineract-CN as it is
> >>    also a micro-services arch.
> >>    - Not fully stateless (some info required to be kept client and
> server
> >>    side to complete fin tranx):  Hmm...
> >>    - Client (side) decided common ID (complexity reduced by relying on
> >>    client to initiate tranx calls):  Maybe not yet in our thinking ?
> >> contrary?
> >>
> >> Similarly, there is a reference to how generic URI's are formed with a
> >> given example:
> >> scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
> >>
> >> and other things like max header size and so forth.
> >>
> >> As I lack the skills to actually work on this code, I'm hoping I can
> >> contribute at the level of conceptual understanding and requirements,
> and
> >> perhaps add to the Documentation if I can understand what is actually
> >> going
> >> on here.  If this is already documented, please send me there.
> >>
> >> ( Myrle - hope this is helpful, if not, let me know please.  )
> >>
> >> Thanks,
> >> - James
> >>
> >>
> >> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
> >> wrote:
> >>
> >> > Hello Myrle,
> >> >
> >> > Trust that you're doing great.
> >> >
> >> > Following your recommendations, I intended solving the issue using a
> >> 3-step
> >> > approach;
> >> >
> >> > 1. Obtain token
> >> > 2. Validate token
> >> > 3. Add token to MockMvc call as a header.
> >> >
> >> > However, I've been unable to get status different from 404 (Not Found)
> >> and
> >> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
> >> one
> >> > of the 3 steps above wrong.
> >> >
> >> > Regarding 1.), I used TenantApplicationSecurityTestRule's
> >> > getPermissionToken() method to obtain some tokens based on Allowed
> >> > operations (Read, Change and Delete) and they were each of the form
> >> > "*Bearer
> >> > eyJhbGciOiJSU....*". Which service actually generates tokens ?
> >> > TenantAccessTokenSerializer
> >> > in anubis ?
> >> >
> >> > Concerning 2.), The tokens I obtained failed the
> >> > SystemSecurityEnvironment's isValidToken() method.  So how can we
> >> validate
> >> > the obtained tokens ?
> >> >
> >> > Regarding 3.), I noticed that Spring MVC Test provides an interface
> >> called
> >> > the RequestPostProcessor
> >> > <
> >> >
> >>
> https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java
> >> > >
> >> > which
> >> > can be used to modify a request. I intend to use this to add a valid
> >> token
> >> > to each MockMvc call. I wrote a method which modifies a request by
> >> > adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> >> > myToken)* and then running each MockMvc call in the unit test with an
> >> > object of the class holding this method.
> >> >
> >> > Also, you mentioned a Spring Security filter which filters requests to
> >> > endpoints. Where exactly is this filter located ? I've been scouring
> >> anubis
> >> > for it to no avail. I'm considering mocking the filter to permit
> >> specific
> >> > tokens or calls go through.
> >> >
> >> > Your help will be greatly appreciated.
> >> >
> >> > At Your Service,
> >> > Isaac Kamga.
> >> >
> >> > On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org>
> wrote:
> >> >
> >> > > Hey Isaac,
> >> > >
> >> > > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <isaac.kamga@mifos.org
> >
> >> > > wrote:
> >> > > > Thanks for your very helpful feedback.
> >> > >
> >> > > You're very welcome.  Thank you for taking it so well.
> >> > >
> >> > > > Do we have to use a different approach ( possibly the
> documentation
> >> > > module
> >> > > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE )
> >> from
> >> > > > synchronous ones (GET) ? This can be done later but I wanted to
> know
> >> > your
> >> > > > thoughts on this.
> >> > >
> >> > > Fortunately we do not.  The asynchronous calls will return an
> >> > > ACCEPTED, and the synchronous calls will return OK.  From the point
> of
> >> > > view of the documentation, and of calling them, that's the only
> >> > > difference.  The asynchronous calls can also return BAD REQUEST for
> >> > > any invalid values which are fast to check (where the synchronous
> ones
> >> > > will return BAD REQUEST for invalid values regardless of how easy
> they
> >> > > are to check.)
> >> > >
> >> > > The documentation module is still an open question for me.  But not
> >> > > because of asynchronous vs synchronous calls.
> >> > >
> >> > > > Thanks for shedding more light on how this works. When I saw how
> >> "easy"
> >> > > it
> >> > > > was to do API calls, I asked myself how one could get to intercept
> >> > > > information such as the status of a response. Building a new test
> >> > harness
> >> > > > that works with mockmvc can be a daunting task. I hope I can count
> >> on
> >> > > your
> >> > > > help when I run into frustrations.
> >> > >
> >> > > I'll do what I can, but I don't know mockmvc.  I've never used it,
> >> > > partly because of this problem.
> >> > >
> >> > > > So far, I created this document
> >> > > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> >> > > +Fineract+CN+API+Documentation>
> >> > > > to
> >> > > > help developers generate the asciidoc files themselves from the
> unit
> >> > > tests.
> >> > > > Would you prefer that we put this in the repository's README file
> or
> >> > > leave
> >> > > > it on confluence ?
> >> > >
> >> > > Let's start off with it where it is, and see whether it works by
> >> > > trying it out there.
> >> > >
> >> > > You're doing good,
> >> > >
> >> > > Best Regards,
> >> > > Myrle
> >> > >
> >> >
> >>
> >
>

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hello there,

Trust that this email finds you in good health.

I just hosted the Apache Fineract CN API documentation
<http://smartfinance.tech/fineract-cn-api-docs/> which I've been working on
so Fineracters can view and give some feedback. This will be quite helpful
for GSoC students and developers working with Fineract CN as well as
business persons who want a feel of the API Documentation. Note that this
is just a temporary site for these docs, they'll eventually be hosted on
Apache infrastructure.

@Myrle Kindly take some time to review the aforementioned Pull Request so
we make progress on that front.

I hope this helps.

At Your Service,
Isaac Kamga.

On Thu, Jun 28, 2018 at 11:21 AM Isaac Kamga <is...@mifos.org> wrote:

> Hi James,
>
> Thanks for your email.
>
> Yes, I think the API documentation can be an important part of the Apache
> Fineract CN project.
>
> The document
> <https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation>
> I wrote which you quoted above helps anyone generate the snippets and view
> the api docs...developers would be okay with it.
> When I'm done with another iteration of the project, I'll update the
> community on how the documentation actually looks.
>
> At Your Service,
> Isaac Kamga.
>
> On Fri, May 25, 2018 at 10:42 PM James Dailey <ja...@gmail.com>
> wrote:
>
>> Isaac - This is a thread I am trying to follow.  Thank you for all the
>> work
>> you're putting in, and to Myrle for being a mentor on this work.  Seems
>> like it is leading to something really important for the project.
>>
>> I wonder if this <
>>
>> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
>> >
>> should or could be expanded to explain and document the API or if we
>> should
>> have a separate API Documentation File.
>>
>> At a requirements level, I'm trying to figure out how Mojaloop APIs and
>> Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN
>> and
>> other outside API driven systems will function together.  On the Mojaloop
>> project they have a 190 page documentation of the standard API starting
>> with some statements that I think may also be relevant to how the
>> Fineract-CN services architecture is set up.
>>
>> https://github.com/mojaloop/mojaloop-specification/blob/master/API%20Definition%20v1.0.pdf
>>
>>
>> Specifically, I'm referring to section 3.1.1. .  Of those characteristics
>> mentioned, which apply to Fineract-CN? :
>>
>>    - Fully Asychronous (esp for long running processes) :  my guess, seems
>>    likely yes on Fineract-CN - yes?
>>    - Decentralized (no central authority):  My current understanding is
>>    that Fineract-CN has dependencies but not centralization?
>>    - Service Oriented :  that seems like a given in Fineract-CN as it is
>>    also a micro-services arch.
>>    - Not fully stateless (some info required to be kept client and server
>>    side to complete fin tranx):  Hmm...
>>    - Client (side) decided common ID (complexity reduced by relying on
>>    client to initiate tranx calls):  Maybe not yet in our thinking ?
>> contrary?
>>
>> Similarly, there is a reference to how generic URI's are formed with a
>> given example:
>> scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
>>
>> and other things like max header size and so forth.
>>
>> As I lack the skills to actually work on this code, I'm hoping I can
>> contribute at the level of conceptual understanding and requirements, and
>> perhaps add to the Documentation if I can understand what is actually
>> going
>> on here.  If this is already documented, please send me there.
>>
>> ( Myrle - hope this is helpful, if not, let me know please.  )
>>
>> Thanks,
>> - James
>>
>>
>> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
>> wrote:
>>
>> > Hello Myrle,
>> >
>> > Trust that you're doing great.
>> >
>> > Following your recommendations, I intended solving the issue using a
>> 3-step
>> > approach;
>> >
>> > 1. Obtain token
>> > 2. Validate token
>> > 3. Add token to MockMvc call as a header.
>> >
>> > However, I've been unable to get status different from 404 (Not Found)
>> and
>> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
>> one
>> > of the 3 steps above wrong.
>> >
>> > Regarding 1.), I used TenantApplicationSecurityTestRule's
>> > getPermissionToken() method to obtain some tokens based on Allowed
>> > operations (Read, Change and Delete) and they were each of the form
>> > "*Bearer
>> > eyJhbGciOiJSU....*". Which service actually generates tokens ?
>> > TenantAccessTokenSerializer
>> > in anubis ?
>> >
>> > Concerning 2.), The tokens I obtained failed the
>> > SystemSecurityEnvironment's isValidToken() method.  So how can we
>> validate
>> > the obtained tokens ?
>> >
>> > Regarding 3.), I noticed that Spring MVC Test provides an interface
>> called
>> > the RequestPostProcessor
>> > <
>> >
>> https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java
>> > >
>> > which
>> > can be used to modify a request. I intend to use this to add a valid
>> token
>> > to each MockMvc call. I wrote a method which modifies a request by
>> > adding a *header(ApiConstants.AUTHORIZATON_HEADER,
>> > myToken)* and then running each MockMvc call in the unit test with an
>> > object of the class holding this method.
>> >
>> > Also, you mentioned a Spring Security filter which filters requests to
>> > endpoints. Where exactly is this filter located ? I've been scouring
>> anubis
>> > for it to no avail. I'm considering mocking the filter to permit
>> specific
>> > tokens or calls go through.
>> >
>> > Your help will be greatly appreciated.
>> >
>> > At Your Service,
>> > Isaac Kamga.
>> >
>> > On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org> wrote:
>> >
>> > > Hey Isaac,
>> > >
>> > > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org>
>> > > wrote:
>> > > > Thanks for your very helpful feedback.
>> > >
>> > > You're very welcome.  Thank you for taking it so well.
>> > >
>> > > > Do we have to use a different approach ( possibly the documentation
>> > > module
>> > > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE )
>> from
>> > > > synchronous ones (GET) ? This can be done later but I wanted to know
>> > your
>> > > > thoughts on this.
>> > >
>> > > Fortunately we do not.  The asynchronous calls will return an
>> > > ACCEPTED, and the synchronous calls will return OK.  From the point of
>> > > view of the documentation, and of calling them, that's the only
>> > > difference.  The asynchronous calls can also return BAD REQUEST for
>> > > any invalid values which are fast to check (where the synchronous ones
>> > > will return BAD REQUEST for invalid values regardless of how easy they
>> > > are to check.)
>> > >
>> > > The documentation module is still an open question for me.  But not
>> > > because of asynchronous vs synchronous calls.
>> > >
>> > > > Thanks for shedding more light on how this works. When I saw how
>> "easy"
>> > > it
>> > > > was to do API calls, I asked myself how one could get to intercept
>> > > > information such as the status of a response. Building a new test
>> > harness
>> > > > that works with mockmvc can be a daunting task. I hope I can count
>> on
>> > > your
>> > > > help when I run into frustrations.
>> > >
>> > > I'll do what I can, but I don't know mockmvc.  I've never used it,
>> > > partly because of this problem.
>> > >
>> > > > So far, I created this document
>> > > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
>> > > +Fineract+CN+API+Documentation>
>> > > > to
>> > > > help developers generate the asciidoc files themselves from the unit
>> > > tests.
>> > > > Would you prefer that we put this in the repository's README file or
>> > > leave
>> > > > it on confluence ?
>> > >
>> > > Let's start off with it where it is, and see whether it works by
>> > > trying it out there.
>> > >
>> > > You're doing good,
>> > >
>> > > Best Regards,
>> > > Myrle
>> > >
>> >
>>
>

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hi James,

Thanks for your email.

Yes, I think the API documentation can be an important part of the Apache
Fineract CN project.

The document
<https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation>
I wrote which you quoted above helps anyone generate the snippets and view
the api docs...developers would be okay with it.
When I'm done with another iteration of the project, I'll update the
community on how the documentation actually looks.

At Your Service,
Isaac Kamga.

On Fri, May 25, 2018 at 10:42 PM James Dailey <ja...@gmail.com>
wrote:

> Isaac - This is a thread I am trying to follow.  Thank you for all the work
> you're putting in, and to Myrle for being a mentor on this work.  Seems
> like it is leading to something really important for the project.
>
> I wonder if this <
>
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
> >
> should or could be expanded to explain and document the API or if we should
> have a separate API Documentation File.
>
> At a requirements level, I'm trying to figure out how Mojaloop APIs and
> Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN and
> other outside API driven systems will function together.  On the Mojaloop
> project they have a 190 page documentation of the standard API starting
> with some statements that I think may also be relevant to how the
> Fineract-CN services architecture is set up.
>
> https://github.com/mojaloop/mojaloop-specification/blob/master/API%20Definition%20v1.0.pdf
>
>
> Specifically, I'm referring to section 3.1.1. .  Of those characteristics
> mentioned, which apply to Fineract-CN? :
>
>    - Fully Asychronous (esp for long running processes) :  my guess, seems
>    likely yes on Fineract-CN - yes?
>    - Decentralized (no central authority):  My current understanding is
>    that Fineract-CN has dependencies but not centralization?
>    - Service Oriented :  that seems like a given in Fineract-CN as it is
>    also a micro-services arch.
>    - Not fully stateless (some info required to be kept client and server
>    side to complete fin tranx):  Hmm...
>    - Client (side) decided common ID (complexity reduced by relying on
>    client to initiate tranx calls):  Maybe not yet in our thinking ?
> contrary?
>
> Similarly, there is a reference to how generic URI's are formed with a
> given example:
> scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
>
> and other things like max header size and so forth.
>
> As I lack the skills to actually work on this code, I'm hoping I can
> contribute at the level of conceptual understanding and requirements, and
> perhaps add to the Documentation if I can understand what is actually going
> on here.  If this is already documented, please send me there.
>
> ( Myrle - hope this is helpful, if not, let me know please.  )
>
> Thanks,
> - James
>
>
> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org> wrote:
>
> > Hello Myrle,
> >
> > Trust that you're doing great.
> >
> > Following your recommendations, I intended solving the issue using a
> 3-step
> > approach;
> >
> > 1. Obtain token
> > 2. Validate token
> > 3. Add token to MockMvc call as a header.
> >
> > However, I've been unable to get status different from 404 (Not Found)
> and
> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
> one
> > of the 3 steps above wrong.
> >
> > Regarding 1.), I used TenantApplicationSecurityTestRule's
> > getPermissionToken() method to obtain some tokens based on Allowed
> > operations (Read, Change and Delete) and they were each of the form
> > "*Bearer
> > eyJhbGciOiJSU....*". Which service actually generates tokens ?
> > TenantAccessTokenSerializer
> > in anubis ?
> >
> > Concerning 2.), The tokens I obtained failed the
> > SystemSecurityEnvironment's isValidToken() method.  So how can we
> validate
> > the obtained tokens ?
> >
> > Regarding 3.), I noticed that Spring MVC Test provides an interface
> called
> > the RequestPostProcessor
> > <
> >
> https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java
> > >
> > which
> > can be used to modify a request. I intend to use this to add a valid
> token
> > to each MockMvc call. I wrote a method which modifies a request by
> > adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> > myToken)* and then running each MockMvc call in the unit test with an
> > object of the class holding this method.
> >
> > Also, you mentioned a Spring Security filter which filters requests to
> > endpoints. Where exactly is this filter located ? I've been scouring
> anubis
> > for it to no avail. I'm considering mocking the filter to permit specific
> > tokens or calls go through.
> >
> > Your help will be greatly appreciated.
> >
> > At Your Service,
> > Isaac Kamga.
> >
> > On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org> wrote:
> >
> > > Hey Isaac,
> > >
> > > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org>
> > > wrote:
> > > > Thanks for your very helpful feedback.
> > >
> > > You're very welcome.  Thank you for taking it so well.
> > >
> > > > Do we have to use a different approach ( possibly the documentation
> > > module
> > > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE )
> from
> > > > synchronous ones (GET) ? This can be done later but I wanted to know
> > your
> > > > thoughts on this.
> > >
> > > Fortunately we do not.  The asynchronous calls will return an
> > > ACCEPTED, and the synchronous calls will return OK.  From the point of
> > > view of the documentation, and of calling them, that's the only
> > > difference.  The asynchronous calls can also return BAD REQUEST for
> > > any invalid values which are fast to check (where the synchronous ones
> > > will return BAD REQUEST for invalid values regardless of how easy they
> > > are to check.)
> > >
> > > The documentation module is still an open question for me.  But not
> > > because of asynchronous vs synchronous calls.
> > >
> > > > Thanks for shedding more light on how this works. When I saw how
> "easy"
> > > it
> > > > was to do API calls, I asked myself how one could get to intercept
> > > > information such as the status of a response. Building a new test
> > harness
> > > > that works with mockmvc can be a daunting task. I hope I can count on
> > > your
> > > > help when I run into frustrations.
> > >
> > > I'll do what I can, but I don't know mockmvc.  I've never used it,
> > > partly because of this problem.
> > >
> > > > So far, I created this document
> > > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> > > +Fineract+CN+API+Documentation>
> > > > to
> > > > help developers generate the asciidoc files themselves from the unit
> > > tests.
> > > > Would you prefer that we put this in the repository's README file or
> > > leave
> > > > it on confluence ?
> > >
> > > Let's start off with it where it is, and see whether it works by
> > > trying it out there.
> > >
> > > You're doing good,
> > >
> > > Best Regards,
> > > Myrle
> > >
> >
>

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hello Myrle,

Thanks a million for pointing these out.

I've updated the Pull request [1] to the fineract-cn-customer repository
based on your feedback....I await your review.

I added the token, tenant and user to the MockMvc call and also removed the
prefix "/customer/v1" from the url's of the endpoints I was calling. From
that point, the endpoints started returning the right status codes.
Thereafter, I tried making the calls without adding token, tenant and user
and they worked the same.

@Seetha, Thank you for reaching out. Endeavor to build Apache Fineract CN
using [2] and kindly scour through Fineract CN's jira page [3] for issues
that pick your interest and get to work on them. We definitely want you to
be a long term contributor to this project.

At Your Service,
Isaac Kamga.

[1] https://github.com/apache/fineract-cn-customer/pull/7
[2]
https://cwiki.apache.org/confluence/display/FINERACT/How+To+Build+Apache+Fineract+CN

[3]
https://jira.apache.org/jira/projects/FINCN/issues/FINCN-75?filter=allopenissues


On Wed, May 30, 2018 at 5:04 PM, Myrle Krantz <my...@apache.org> wrote:

> One more note:
>
> Isaac, if Seetha wants to help out on this, it would make a lot of
> sense to create branches in the apache repositories.  That way any of
> us can merge her PR's.  I suggest naming the branch FINCN-6.
>
> Best Regards,
> Myrle
>
> On Wed, May 30, 2018 at 5:43 PM, Myrle Krantz <my...@apache.org> wrote:
> > Seetha,
> >
> > Thank you very much for the offer of help.
> >
> > But if you've looked at Isaac's branch (1) and have concrete ideas on
> > how to do it better, feel free to jump in with suggestions or PRs
> > right away.  If you're not sure how to participate, then perhaps wait
> > a little bit longer until Isaac has his concept worked out.  Once
> > Isaac has his concept worked out, he'll probably want to touch all of
> > the services, and then your help would definitely speed things up.
> >
> > Best Regards,
> > Myrle
> >
> > 1.) https://github.com/Izakey/fineract-cn-customer/tree/PocFromIsaac
> >
> > On Sat, May 26, 2018 at 11:46 PM, Seetha Hegde <se...@gmail.com>
> wrote:
> >> I am interested in this project. I have experience in REST Web
> >> services but not much in Spring Security. Let me know if you need help
> >> with coding.
> >>
> >> thanks
> >> Seetha
>

Re: Apache Fineract CN API Documentation

[Myrle Krantz <my...@apache.org>]

One more note:

Isaac, if Seetha wants to help out on this, it would make a lot of
sense to create branches in the apache repositories.  That way any of
us can merge her PR's.  I suggest naming the branch FINCN-6.

Best Regards,
Myrle

On Wed, May 30, 2018 at 5:43 PM, Myrle Krantz <my...@apache.org> wrote:
> Seetha,
>
> Thank you very much for the offer of help.
>
> But if you've looked at Isaac's branch (1) and have concrete ideas on
> how to do it better, feel free to jump in with suggestions or PRs
> right away.  If you're not sure how to participate, then perhaps wait
> a little bit longer until Isaac has his concept worked out.  Once
> Isaac has his concept worked out, he'll probably want to touch all of
> the services, and then your help would definitely speed things up.
>
> Best Regards,
> Myrle
>
> 1.) https://github.com/Izakey/fineract-cn-customer/tree/PocFromIsaac
>
> On Sat, May 26, 2018 at 11:46 PM, Seetha Hegde <se...@gmail.com> wrote:
>> I am interested in this project. I have experience in REST Web
>> services but not much in Spring Security. Let me know if you need help
>> with coding.
>>
>> thanks
>> Seetha

Re: Apache Fineract CN API Documentation

[Myrle Krantz <my...@apache.org>]

Seetha,

Thank you very much for the offer of help.

But if you've looked at Isaac's branch (1) and have concrete ideas on
how to do it better, feel free to jump in with suggestions or PRs
right away.  If you're not sure how to participate, then perhaps wait
a little bit longer until Isaac has his concept worked out.  Once
Isaac has his concept worked out, he'll probably want to touch all of
the services, and then your help would definitely speed things up.

Best Regards,
Myrle

1.) https://github.com/Izakey/fineract-cn-customer/tree/PocFromIsaac

On Sat, May 26, 2018 at 11:46 PM, Seetha Hegde <se...@gmail.com> wrote:
> I am interested in this project. I have experience in REST Web
> services but not much in Spring Security. Let me know if you need help
> with coding.
>
> thanks
> Seetha

Re: Apache Fineract CN API Documentation

[Seetha Hegde <se...@gmail.com>]

I am interested in this project. I have experience in REST Web
services but not much in Spring Security. Let me know if you need help
with coding.

thanks
Seetha

On Sat, May 26, 2018 at 10:57 AM, Ed Cable <ed...@mifos.org> wrote:
> Myrle,
>
> Thanks for your reply to James.
>
>>
>> I think the usefulness of discussing this in the abstract is limited.
>> If you want to get this working, you'll need to find someone to
>> program it, or do it yourself.  If you don't yet have these skills,
>> you can learn them.  If you want someone else to do it, you'll
>> probably need to pay them.  If you or someone else does decide to work
>> on it and to do it as open source, I'll be glad to provide moral and
>> technical support, within certain limits.
>>
>
> Steve indeed is heading up this work from the community along with support
> with Rahul and the integration with Mojaloop will be part of the scope of
> the work that Sanyam is doing for the Mifos Initiative for GSOC on a
> payment bridge service between Fineract and external payment systems like
> mobile money
>
> Hopefully Steve and Rahul will have a chance to reply to James'
> suggestions/questions about connecting Fineract CN to other outside
> API-driven systems in general.
>
>
>> Best Regards,
>> Myrle
>>
>> On Fri, May 25, 2018 at 11:42 PM, James Dailey <ja...@gmail.com>
>> wrote:
>> > Isaac - This is a thread I am trying to follow.  Thank you for all the
>> work
>> > you're putting in, and to Myrle for being a mentor on this work.  Seems
>> > like it is leading to something really important for the project.
>> >
>> > I wonder if this <
>> >
>> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
>> >>
>> > should or could be expanded to explain and document the API or if we
>> should
>> > have a separate API Documentation File.
>> >
>> > At a requirements level, I'm trying to figure out how Mojaloop APIs and
>> > Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN
>> and
>> > other outside API driven systems will function together.  On the Mojaloop
>> > project they have a 190 page documentation of the standard API starting
>> > with some statements that I think may also be relevant to how the
>> > Fineract-CN services architecture is set up.
>> >
>> https://github.com/mojaloop/mojaloop-specification/blob/master/API%20Definition%20v1.0.pdf
>> >
>> >
>> > Specifically, I'm referring to section 3.1.1. .  Of those characteristics
>> > mentioned, which apply to Fineract-CN? :
>> >
>> >    - Fully Asychronous (esp for long running processes) :  my guess,
>> seems
>> >    likely yes on Fineract-CN - yes?
>> >    - Decentralized (no central authority):  My current understanding is
>> >    that Fineract-CN has dependencies but not centralization?
>> >    - Service Oriented :  that seems like a given in Fineract-CN as it is
>> >    also a micro-services arch.
>> >    - Not fully stateless (some info required to be kept client and server
>> >    side to complete fin tranx):  Hmm...
>> >    - Client (side) decided common ID (complexity reduced by relying on
>> >    client to initiate tranx calls):  Maybe not yet in our thinking ?
>> contrary?
>> >
>> > Similarly, there is a reference to how generic URI's are formed with a
>> > given example:
>> > scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
>> >
>> > and other things like max header size and so forth.
>> >
>> > As I lack the skills to actually work on this code, I'm hoping I can
>> > contribute at the level of conceptual understanding and requirements, and
>> > perhaps add to the Documentation if I can understand what is actually
>> going
>> > on here.  If this is already documented, please send me there.
>> >
>> > ( Myrle - hope this is helpful, if not, let me know please.  )
>> >
>> > Thanks,
>> > - James
>> >
>> >
>> > On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
>> wrote:
>> >
>> >> Hello Myrle,
>> >>
>> >> Trust that you're doing great.
>> >>
>> >> Following your recommendations, I intended solving the issue using a
>> 3-step
>> >> approach;
>> >>
>> >> 1. Obtain token
>> >> 2. Validate token
>> >> 3. Add token to MockMvc call as a header.
>> >>
>> >> However, I've been unable to get status different from 404 (Not Found)
>> and
>> >> 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
>> one
>> >> of the 3 steps above wrong.
>> >>
>> >> Regarding 1.), I used TenantApplicationSecurityTestRule's
>> >> getPermissionToken() method to obtain some tokens based on Allowed
>> >> operations (Read, Change and Delete) and they were each of the form
>> >> "*Bearer
>> >> eyJhbGciOiJSU....*". Which service actually generates tokens ?
>> >> TenantAccessTokenSerializer
>> >> in anubis ?
>> >>
>> >> Concerning 2.), The tokens I obtained failed the
>> >> SystemSecurityEnvironment's isValidToken() method.  So how can we
>> validate
>> >> the obtained tokens ?
>> >>
>> >> Regarding 3.), I noticed that Spring MVC Test provides an interface
>> called
>> >> the RequestPostProcessor
>> >> <
>> >>
>> https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java
>> >> >
>> >> which
>> >> can be used to modify a request. I intend to use this to add a valid
>> token
>> >> to each MockMvc call. I wrote a method which modifies a request by
>> >> adding a *header(ApiConstants.AUTHORIZATON_HEADER,
>> >> myToken)* and then running each MockMvc call in the unit test with an
>> >> object of the class holding this method.
>> >>
>> >> Also, you mentioned a Spring Security filter which filters requests to
>> >> endpoints. Where exactly is this filter located ? I've been scouring
>> anubis
>> >> for it to no avail. I'm considering mocking the filter to permit
>> specific
>> >> tokens or calls go through.
>> >>
>> >> Your help will be greatly appreciated.
>> >>
>> >> At Your Service,
>> >> Isaac Kamga.
>> >>
>> >> On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org> wrote:
>> >>
>> >> > Hey Isaac,
>> >> >
>> >> > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org>
>> >> > wrote:
>> >> > > Thanks for your very helpful feedback.
>> >> >
>> >> > You're very welcome.  Thank you for taking it so well.
>> >> >
>> >> > > Do we have to use a different approach ( possibly the documentation
>> >> > module
>> >> > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE )
>> from
>> >> > > synchronous ones (GET) ? This can be done later but I wanted to know
>> >> your
>> >> > > thoughts on this.
>> >> >
>> >> > Fortunately we do not.  The asynchronous calls will return an
>> >> > ACCEPTED, and the synchronous calls will return OK.  From the point of
>> >> > view of the documentation, and of calling them, that's the only
>> >> > difference.  The asynchronous calls can also return BAD REQUEST for
>> >> > any invalid values which are fast to check (where the synchronous ones
>> >> > will return BAD REQUEST for invalid values regardless of how easy they
>> >> > are to check.)
>> >> >
>> >> > The documentation module is still an open question for me.  But not
>> >> > because of asynchronous vs synchronous calls.
>> >> >
>> >> > > Thanks for shedding more light on how this works. When I saw how
>> "easy"
>> >> > it
>> >> > > was to do API calls, I asked myself how one could get to intercept
>> >> > > information such as the status of a response. Building a new test
>> >> harness
>> >> > > that works with mockmvc can be a daunting task. I hope I can count
>> on
>> >> > your
>> >> > > help when I run into frustrations.
>> >> >
>> >> > I'll do what I can, but I don't know mockmvc.  I've never used it,
>> >> > partly because of this problem.
>> >> >
>> >> > > So far, I created this document
>> >> > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
>> >> > +Fineract+CN+API+Documentation>
>> >> > > to
>> >> > > help developers generate the asciidoc files themselves from the unit
>> >> > tests.
>> >> > > Would you prefer that we put this in the repository's README file or
>> >> > leave
>> >> > > it on confluence ?
>> >> >
>> >> > Let's start off with it where it is, and see whether it works by
>> >> > trying it out there.
>> >> >
>> >> > You're doing good,
>> >> >
>> >> > Best Regards,
>> >> > Myrle
>> >> >
>> >>
>>
>
>
> --
> *Ed Cable*
> President/CEO, Mifos Initiative
> edcable@mifos.org | Skype: edcable | Mobile: +1.484.477.8649
>
> *Collectively Creating a World of 3 Billion Maries | *http://mifos.org
> <http://facebook.com/mifos>  <http://www.twitter.com/mifos>

Re: Apache Fineract CN API Documentation

[Steve Conrad <sc...@gmail.com>]

I am just catching up on this thread. I am not familiar with the
architecture of Fineract CN, but have been working on integrating Fineract
with Mojaloop and hopefully can shed some light on the requirements.

In the Payment Gateway implementation that we are currently working on, we
are using ActiveMQ to send and receive messages from a Fineract instance to
perform specific work/transactions. The gateway code manages integrations
with different providers, including Mojaloop. Rahul and Sanyam are working
to architect the payment gateway in such a way that it will be usable by
Fineract CN as well.

Using this architecture, I was able to successfully perform a P2P transfer
between 2 users on 2 different Fineract instances through Mojaloop. The
gateway manages the long running transactions, the unique identifiers
(UUIDs) and the cryptographic verification of transactions.

In order to ensure that the work that we are doing on the payment gateway
will be compatible with Fineract CN, we should follow the same AMQ message
format that is being used in Fineract-CN. Myrle, are there
specifications/documentation on AMQ messages for Fineract CN?

If there are specific questions, please let me know. I am working on
writing up some of my findings and will bring that to the list in the
Mojaloop integration thread.
Thanks,
Steve


On Sat, May 26, 2018 at 9:57 AM, Ed Cable <ed...@mifos.org> wrote:

> Myrle,
>
> Thanks for your reply to James.
>
> >
> > I think the usefulness of discussing this in the abstract is limited.
> > If you want to get this working, you'll need to find someone to
> > program it, or do it yourself.  If you don't yet have these skills,
> > you can learn them.  If you want someone else to do it, you'll
> > probably need to pay them.  If you or someone else does decide to work
> > on it and to do it as open source, I'll be glad to provide moral and
> > technical support, within certain limits.
> >
>
> Steve indeed is heading up this work from the community along with support
> with Rahul and the integration with Mojaloop will be part of the scope of
> the work that Sanyam is doing for the Mifos Initiative for GSOC on a
> payment bridge service between Fineract and external payment systems like
> mobile money
>
> Hopefully Steve and Rahul will have a chance to reply to James'
> suggestions/questions about connecting Fineract CN to other outside
> API-driven systems in general.
>
>
> > Best Regards,
> > Myrle
> >
> > On Fri, May 25, 2018 at 11:42 PM, James Dailey <ja...@gmail.com>
> > wrote:
> > > Isaac - This is a thread I am trying to follow.  Thank you for all the
> > work
> > > you're putting in, and to Myrle for being a mentor on this work.  Seems
> > > like it is leading to something really important for the project.
> > >
> > > I wonder if this <
> > >
> > https://cwiki.apache.org/confluence/display/FINERACT/Apache+
> Fineract+CN+API+Documentation
> > >>
> > > should or could be expanded to explain and document the API or if we
> > should
> > > have a separate API Documentation File.
> > >
> > > At a requirements level, I'm trying to figure out how Mojaloop APIs and
> > > Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN
> > and
> > > other outside API driven systems will function together.  On the
> Mojaloop
> > > project they have a 190 page documentation of the standard API starting
> > > with some statements that I think may also be relevant to how the
> > > Fineract-CN services architecture is set up.
> > >
> > https://github.com/mojaloop/mojaloop-specification/blob/mast
> er/API%20Definition%20v1.0.pdf
> > >
> > >
> > > Specifically, I'm referring to section 3.1.1. .  Of those
> characteristics
> > > mentioned, which apply to Fineract-CN? :
> > >
> > >    - Fully Asychronous (esp for long running processes) :  my guess,
> > seems
> > >    likely yes on Fineract-CN - yes?
> > >    - Decentralized (no central authority):  My current understanding is
> > >    that Fineract-CN has dependencies but not centralization?
> > >    - Service Oriented :  that seems like a given in Fineract-CN as it
> is
> > >    also a micro-services arch.
> > >    - Not fully stateless (some info required to be kept client and
> server
> > >    side to complete fin tranx):  Hmm...
> > >    - Client (side) decided common ID (complexity reduced by relying on
> > >    client to initiate tranx calls):  Maybe not yet in our thinking ?
> > contrary?
> > >
> > > Similarly, there is a reference to how generic URI's are formed with a
> > > given example:
> > > scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
> > >
> > > and other things like max header size and so forth.
> > >
> > > As I lack the skills to actually work on this code, I'm hoping I can
> > > contribute at the level of conceptual understanding and requirements,
> and
> > > perhaps add to the Documentation if I can understand what is actually
> > going
> > > on here.  If this is already documented, please send me there.
> > >
> > > ( Myrle - hope this is helpful, if not, let me know please.  )
> > >
> > > Thanks,
> > > - James
> > >
> > >
> > > On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
> > wrote:
> > >
> > >> Hello Myrle,
> > >>
> > >> Trust that you're doing great.
> > >>
> > >> Following your recommendations, I intended solving the issue using a
> > 3-step
> > >> approach;
> > >>
> > >> 1. Obtain token
> > >> 2. Validate token
> > >> 3. Add token to MockMvc call as a header.
> > >>
> > >> However, I've been unable to get status different from 404 (Not Found)
> > and
> > >> 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
> > one
> > >> of the 3 steps above wrong.
> > >>
> > >> Regarding 1.), I used TenantApplicationSecurityTestRule's
> > >> getPermissionToken() method to obtain some tokens based on Allowed
> > >> operations (Read, Change and Delete) and they were each of the form
> > >> "*Bearer
> > >> eyJhbGciOiJSU....*". Which service actually generates tokens ?
> > >> TenantAccessTokenSerializer
> > >> in anubis ?
> > >>
> > >> Concerning 2.), The tokens I obtained failed the
> > >> SystemSecurityEnvironment's isValidToken() method.  So how can we
> > validate
> > >> the obtained tokens ?
> > >>
> > >> Regarding 3.), I noticed that Spring MVC Test provides an interface
> > called
> > >> the RequestPostProcessor
> > >> <
> > >>
> > https://github.com/spring-projects/spring-framework/blob/
> master/spring-test/src/main/java/org/springframework/test/
> web/servlet/request/RequestPostProcessor.java
> > >> >
> > >> which
> > >> can be used to modify a request. I intend to use this to add a valid
> > token
> > >> to each MockMvc call. I wrote a method which modifies a request by
> > >> adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> > >> myToken)* and then running each MockMvc call in the unit test with an
> > >> object of the class holding this method.
> > >>
> > >> Also, you mentioned a Spring Security filter which filters requests to
> > >> endpoints. Where exactly is this filter located ? I've been scouring
> > anubis
> > >> for it to no avail. I'm considering mocking the filter to permit
> > specific
> > >> tokens or calls go through.
> > >>
> > >> Your help will be greatly appreciated.
> > >>
> > >> At Your Service,
> > >> Isaac Kamga.
> > >>
> > >> On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org>
> wrote:
> > >>
> > >> > Hey Isaac,
> > >> >
> > >> > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <isaac.kamga@mifos.org
> >
> > >> > wrote:
> > >> > > Thanks for your very helpful feedback.
> > >> >
> > >> > You're very welcome.  Thank you for taking it so well.
> > >> >
> > >> > > Do we have to use a different approach ( possibly the
> documentation
> > >> > module
> > >> > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE )
> > from
> > >> > > synchronous ones (GET) ? This can be done later but I wanted to
> know
> > >> your
> > >> > > thoughts on this.
> > >> >
> > >> > Fortunately we do not.  The asynchronous calls will return an
> > >> > ACCEPTED, and the synchronous calls will return OK.  From the point
> of
> > >> > view of the documentation, and of calling them, that's the only
> > >> > difference.  The asynchronous calls can also return BAD REQUEST for
> > >> > any invalid values which are fast to check (where the synchronous
> ones
> > >> > will return BAD REQUEST for invalid values regardless of how easy
> they
> > >> > are to check.)
> > >> >
> > >> > The documentation module is still an open question for me.  But not
> > >> > because of asynchronous vs synchronous calls.
> > >> >
> > >> > > Thanks for shedding more light on how this works. When I saw how
> > "easy"
> > >> > it
> > >> > > was to do API calls, I asked myself how one could get to intercept
> > >> > > information such as the status of a response. Building a new test
> > >> harness
> > >> > > that works with mockmvc can be a daunting task. I hope I can count
> > on
> > >> > your
> > >> > > help when I run into frustrations.
> > >> >
> > >> > I'll do what I can, but I don't know mockmvc.  I've never used it,
> > >> > partly because of this problem.
> > >> >
> > >> > > So far, I created this document
> > >> > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> > >> > +Fineract+CN+API+Documentation>
> > >> > > to
> > >> > > help developers generate the asciidoc files themselves from the
> unit
> > >> > tests.
> > >> > > Would you prefer that we put this in the repository's README file
> or
> > >> > leave
> > >> > > it on confluence ?
> > >> >
> > >> > Let's start off with it where it is, and see whether it works by
> > >> > trying it out there.
> > >> >
> > >> > You're doing good,
> > >> >
> > >> > Best Regards,
> > >> > Myrle
> > >> >
> > >>
> >
>
>
> --
> *Ed Cable*
> President/CEO, Mifos Initiative
> edcable@mifos.org | Skype: edcable | Mobile: +1.484.477.8649
>
> *Collectively Creating a World of 3 Billion Maries | *http://mifos.org
> <http://facebook.com/mifos>  <http://www.twitter.com/mifos>
>

Re: Apache Fineract CN API Documentation

[Ed Cable <ed...@mifos.org>]

Myrle,

Thanks for your reply to James.

>
> I think the usefulness of discussing this in the abstract is limited.
> If you want to get this working, you'll need to find someone to
> program it, or do it yourself.  If you don't yet have these skills,
> you can learn them.  If you want someone else to do it, you'll
> probably need to pay them.  If you or someone else does decide to work
> on it and to do it as open source, I'll be glad to provide moral and
> technical support, within certain limits.
>

Steve indeed is heading up this work from the community along with support
with Rahul and the integration with Mojaloop will be part of the scope of
the work that Sanyam is doing for the Mifos Initiative for GSOC on a
payment bridge service between Fineract and external payment systems like
mobile money

Hopefully Steve and Rahul will have a chance to reply to James'
suggestions/questions about connecting Fineract CN to other outside
API-driven systems in general.


> Best Regards,
> Myrle
>
> On Fri, May 25, 2018 at 11:42 PM, James Dailey <ja...@gmail.com>
> wrote:
> > Isaac - This is a thread I am trying to follow.  Thank you for all the
> work
> > you're putting in, and to Myrle for being a mentor on this work.  Seems
> > like it is leading to something really important for the project.
> >
> > I wonder if this <
> >
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
> >>
> > should or could be expanded to explain and document the API or if we
> should
> > have a separate API Documentation File.
> >
> > At a requirements level, I'm trying to figure out how Mojaloop APIs and
> > Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN
> and
> > other outside API driven systems will function together.  On the Mojaloop
> > project they have a 190 page documentation of the standard API starting
> > with some statements that I think may also be relevant to how the
> > Fineract-CN services architecture is set up.
> >
> https://github.com/mojaloop/mojaloop-specification/blob/master/API%20Definition%20v1.0.pdf
> >
> >
> > Specifically, I'm referring to section 3.1.1. .  Of those characteristics
> > mentioned, which apply to Fineract-CN? :
> >
> >    - Fully Asychronous (esp for long running processes) :  my guess,
> seems
> >    likely yes on Fineract-CN - yes?
> >    - Decentralized (no central authority):  My current understanding is
> >    that Fineract-CN has dependencies but not centralization?
> >    - Service Oriented :  that seems like a given in Fineract-CN as it is
> >    also a micro-services arch.
> >    - Not fully stateless (some info required to be kept client and server
> >    side to complete fin tranx):  Hmm...
> >    - Client (side) decided common ID (complexity reduced by relying on
> >    client to initiate tranx calls):  Maybe not yet in our thinking ?
> contrary?
> >
> > Similarly, there is a reference to how generic URI's are formed with a
> > given example:
> > scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
> >
> > and other things like max header size and so forth.
> >
> > As I lack the skills to actually work on this code, I'm hoping I can
> > contribute at the level of conceptual understanding and requirements, and
> > perhaps add to the Documentation if I can understand what is actually
> going
> > on here.  If this is already documented, please send me there.
> >
> > ( Myrle - hope this is helpful, if not, let me know please.  )
> >
> > Thanks,
> > - James
> >
> >
> > On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org>
> wrote:
> >
> >> Hello Myrle,
> >>
> >> Trust that you're doing great.
> >>
> >> Following your recommendations, I intended solving the issue using a
> 3-step
> >> approach;
> >>
> >> 1. Obtain token
> >> 2. Validate token
> >> 3. Add token to MockMvc call as a header.
> >>
> >> However, I've been unable to get status different from 404 (Not Found)
> and
> >> 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
> one
> >> of the 3 steps above wrong.
> >>
> >> Regarding 1.), I used TenantApplicationSecurityTestRule's
> >> getPermissionToken() method to obtain some tokens based on Allowed
> >> operations (Read, Change and Delete) and they were each of the form
> >> "*Bearer
> >> eyJhbGciOiJSU....*". Which service actually generates tokens ?
> >> TenantAccessTokenSerializer
> >> in anubis ?
> >>
> >> Concerning 2.), The tokens I obtained failed the
> >> SystemSecurityEnvironment's isValidToken() method.  So how can we
> validate
> >> the obtained tokens ?
> >>
> >> Regarding 3.), I noticed that Spring MVC Test provides an interface
> called
> >> the RequestPostProcessor
> >> <
> >>
> https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java
> >> >
> >> which
> >> can be used to modify a request. I intend to use this to add a valid
> token
> >> to each MockMvc call. I wrote a method which modifies a request by
> >> adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> >> myToken)* and then running each MockMvc call in the unit test with an
> >> object of the class holding this method.
> >>
> >> Also, you mentioned a Spring Security filter which filters requests to
> >> endpoints. Where exactly is this filter located ? I've been scouring
> anubis
> >> for it to no avail. I'm considering mocking the filter to permit
> specific
> >> tokens or calls go through.
> >>
> >> Your help will be greatly appreciated.
> >>
> >> At Your Service,
> >> Isaac Kamga.
> >>
> >> On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org> wrote:
> >>
> >> > Hey Isaac,
> >> >
> >> > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org>
> >> > wrote:
> >> > > Thanks for your very helpful feedback.
> >> >
> >> > You're very welcome.  Thank you for taking it so well.
> >> >
> >> > > Do we have to use a different approach ( possibly the documentation
> >> > module
> >> > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE )
> from
> >> > > synchronous ones (GET) ? This can be done later but I wanted to know
> >> your
> >> > > thoughts on this.
> >> >
> >> > Fortunately we do not.  The asynchronous calls will return an
> >> > ACCEPTED, and the synchronous calls will return OK.  From the point of
> >> > view of the documentation, and of calling them, that's the only
> >> > difference.  The asynchronous calls can also return BAD REQUEST for
> >> > any invalid values which are fast to check (where the synchronous ones
> >> > will return BAD REQUEST for invalid values regardless of how easy they
> >> > are to check.)
> >> >
> >> > The documentation module is still an open question for me.  But not
> >> > because of asynchronous vs synchronous calls.
> >> >
> >> > > Thanks for shedding more light on how this works. When I saw how
> "easy"
> >> > it
> >> > > was to do API calls, I asked myself how one could get to intercept
> >> > > information such as the status of a response. Building a new test
> >> harness
> >> > > that works with mockmvc can be a daunting task. I hope I can count
> on
> >> > your
> >> > > help when I run into frustrations.
> >> >
> >> > I'll do what I can, but I don't know mockmvc.  I've never used it,
> >> > partly because of this problem.
> >> >
> >> > > So far, I created this document
> >> > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> >> > +Fineract+CN+API+Documentation>
> >> > > to
> >> > > help developers generate the asciidoc files themselves from the unit
> >> > tests.
> >> > > Would you prefer that we put this in the repository's README file or
> >> > leave
> >> > > it on confluence ?
> >> >
> >> > Let's start off with it where it is, and see whether it works by
> >> > trying it out there.
> >> >
> >> > You're doing good,
> >> >
> >> > Best Regards,
> >> > Myrle
> >> >
> >>
>


-- 
*Ed Cable*
President/CEO, Mifos Initiative
edcable@mifos.org | Skype: edcable | Mobile: +1.484.477.8649

*Collectively Creating a World of 3 Billion Maries | *http://mifos.org
<http://facebook.com/mifos>  <http://www.twitter.com/mifos>

Re: Apache Fineract CN API Documentation

[Myrle Krantz <my...@apache.org>]

James,

In order to help you, I will need to understand what you are actually
trying to do.  I skimmed the section of your document that you named,
but I don't have time to read a 190 page document.

I suspect you are trying to write a REST service which would connect
Fineract CN and mojaloop.
* Is your question whether a service can be written with the
properties you've listed?  If that is your question, the answer is
"yes".  In particular, the client does set financial transaction
identifiers (though it's not clear from that part of the document that
financial transaction ids is what is being refered to there.)
* Is your question whether one of the services in Fineract CN has
those properties?  If that is your question, then the answer is "not
fully".  In particular, Fineract CN transmits information about
completed work via ActiveMQ and not per REST callbacks.

I think the usefulness of discussing this in the abstract is limited.
If you want to get this working, you'll need to find someone to
program it, or do it yourself.  If you don't yet have these skills,
you can learn them.  If you want someone else to do it, you'll
probably need to pay them.  If you or someone else does decide to work
on it and to do it as open source, I'll be glad to provide moral and
technical support, within certain limits.

Best Regards,
Myrle

On Fri, May 25, 2018 at 11:42 PM, James Dailey <ja...@gmail.com> wrote:
> Isaac - This is a thread I am trying to follow.  Thank you for all the work
> you're putting in, and to Myrle for being a mentor on this work.  Seems
> like it is leading to something really important for the project.
>
> I wonder if this <
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
>>
> should or could be expanded to explain and document the API or if we should
> have a separate API Documentation File.
>
> At a requirements level, I'm trying to figure out how Mojaloop APIs and
> Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN and
> other outside API driven systems will function together.  On the Mojaloop
> project they have a 190 page documentation of the standard API starting
> with some statements that I think may also be relevant to how the
> Fineract-CN services architecture is set up.
> https://github.com/mojaloop/mojaloop-specification/blob/master/API%20Definition%20v1.0.pdf
>
>
> Specifically, I'm referring to section 3.1.1. .  Of those characteristics
> mentioned, which apply to Fineract-CN? :
>
>    - Fully Asychronous (esp for long running processes) :  my guess, seems
>    likely yes on Fineract-CN - yes?
>    - Decentralized (no central authority):  My current understanding is
>    that Fineract-CN has dependencies but not centralization?
>    - Service Oriented :  that seems like a given in Fineract-CN as it is
>    also a micro-services arch.
>    - Not fully stateless (some info required to be kept client and server
>    side to complete fin tranx):  Hmm...
>    - Client (side) decided common ID (complexity reduced by relying on
>    client to initiate tranx calls):  Maybe not yet in our thinking ? contrary?
>
> Similarly, there is a reference to how generic URI's are formed with a
> given example:
> scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
>
> and other things like max header size and so forth.
>
> As I lack the skills to actually work on this code, I'm hoping I can
> contribute at the level of conceptual understanding and requirements, and
> perhaps add to the Documentation if I can understand what is actually going
> on here.  If this is already documented, please send me there.
>
> ( Myrle - hope this is helpful, if not, let me know please.  )
>
> Thanks,
> - James
>
>
> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org> wrote:
>
>> Hello Myrle,
>>
>> Trust that you're doing great.
>>
>> Following your recommendations, I intended solving the issue using a 3-step
>> approach;
>>
>> 1. Obtain token
>> 2. Validate token
>> 3. Add token to MockMvc call as a header.
>>
>> However, I've been unable to get status different from 404 (Not Found) and
>> 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least one
>> of the 3 steps above wrong.
>>
>> Regarding 1.), I used TenantApplicationSecurityTestRule's
>> getPermissionToken() method to obtain some tokens based on Allowed
>> operations (Read, Change and Delete) and they were each of the form
>> "*Bearer
>> eyJhbGciOiJSU....*". Which service actually generates tokens ?
>> TenantAccessTokenSerializer
>> in anubis ?
>>
>> Concerning 2.), The tokens I obtained failed the
>> SystemSecurityEnvironment's isValidToken() method.  So how can we validate
>> the obtained tokens ?
>>
>> Regarding 3.), I noticed that Spring MVC Test provides an interface called
>> the RequestPostProcessor
>> <
>> https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java
>> >
>> which
>> can be used to modify a request. I intend to use this to add a valid token
>> to each MockMvc call. I wrote a method which modifies a request by
>> adding a *header(ApiConstants.AUTHORIZATON_HEADER,
>> myToken)* and then running each MockMvc call in the unit test with an
>> object of the class holding this method.
>>
>> Also, you mentioned a Spring Security filter which filters requests to
>> endpoints. Where exactly is this filter located ? I've been scouring anubis
>> for it to no avail. I'm considering mocking the filter to permit specific
>> tokens or calls go through.
>>
>> Your help will be greatly appreciated.
>>
>> At Your Service,
>> Isaac Kamga.
>>
>> On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org> wrote:
>>
>> > Hey Isaac,
>> >
>> > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org>
>> > wrote:
>> > > Thanks for your very helpful feedback.
>> >
>> > You're very welcome.  Thank you for taking it so well.
>> >
>> > > Do we have to use a different approach ( possibly the documentation
>> > module
>> > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE ) from
>> > > synchronous ones (GET) ? This can be done later but I wanted to know
>> your
>> > > thoughts on this.
>> >
>> > Fortunately we do not.  The asynchronous calls will return an
>> > ACCEPTED, and the synchronous calls will return OK.  From the point of
>> > view of the documentation, and of calling them, that's the only
>> > difference.  The asynchronous calls can also return BAD REQUEST for
>> > any invalid values which are fast to check (where the synchronous ones
>> > will return BAD REQUEST for invalid values regardless of how easy they
>> > are to check.)
>> >
>> > The documentation module is still an open question for me.  But not
>> > because of asynchronous vs synchronous calls.
>> >
>> > > Thanks for shedding more light on how this works. When I saw how "easy"
>> > it
>> > > was to do API calls, I asked myself how one could get to intercept
>> > > information such as the status of a response. Building a new test
>> harness
>> > > that works with mockmvc can be a daunting task. I hope I can count on
>> > your
>> > > help when I run into frustrations.
>> >
>> > I'll do what I can, but I don't know mockmvc.  I've never used it,
>> > partly because of this problem.
>> >
>> > > So far, I created this document
>> > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
>> > +Fineract+CN+API+Documentation>
>> > > to
>> > > help developers generate the asciidoc files themselves from the unit
>> > tests.
>> > > Would you prefer that we put this in the repository's README file or
>> > leave
>> > > it on confluence ?
>> >
>> > Let's start off with it where it is, and see whether it works by
>> > trying it out there.
>> >
>> > You're doing good,
>> >
>> > Best Regards,
>> > Myrle
>> >
>>

Re: Apache Fineract CN API Documentation

[James Dailey <ja...@gmail.com>]

Isaac - This is a thread I am trying to follow.  Thank you for all the work
you're putting in, and to Myrle for being a mentor on this work.  Seems
like it is leading to something really important for the project.

I wonder if this <
https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
>
should or could be expanded to explain and document the API or if we should
have a separate API Documentation File.

At a requirements level, I'm trying to figure out how Mojaloop APIs and
Fineract-CN APIs would interact, perhaps as a model for how Fineract-CN and
other outside API driven systems will function together.  On the Mojaloop
project they have a 190 page documentation of the standard API starting
with some statements that I think may also be relevant to how the
Fineract-CN services architecture is set up.
https://github.com/mojaloop/mojaloop-specification/blob/master/API%20Definition%20v1.0.pdf


Specifically, I'm referring to section 3.1.1. .  Of those characteristics
mentioned, which apply to Fineract-CN? :

   - Fully Asychronous (esp for long running processes) :  my guess, seems
   likely yes on Fineract-CN - yes?
   - Decentralized (no central authority):  My current understanding is
   that Fineract-CN has dependencies but not centralization?
   - Service Oriented :  that seems like a given in Fineract-CN as it is
   also a micro-services arch.
   - Not fully stateless (some info required to be kept client and server
   side to complete fin tranx):  Hmm...
   - Client (side) decided common ID (complexity reduced by relying on
   client to initiate tranx calls):  Maybe not yet in our thinking ? contrary?

Similarly, there is a reference to how generic URI's are formed with a
given example:
scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]

and other things like max header size and so forth.

As I lack the skills to actually work on this code, I'm hoping I can
contribute at the level of conceptual understanding and requirements, and
perhaps add to the Documentation if I can understand what is actually going
on here.  If this is already documented, please send me there.

( Myrle - hope this is helpful, if not, let me know please.  )

Thanks,
- James


On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <is...@mifos.org> wrote:

> Hello Myrle,
>
> Trust that you're doing great.
>
> Following your recommendations, I intended solving the issue using a 3-step
> approach;
>
> 1. Obtain token
> 2. Validate token
> 3. Add token to MockMvc call as a header.
>
> However, I've been unable to get status different from 404 (Not Found) and
> 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least one
> of the 3 steps above wrong.
>
> Regarding 1.), I used TenantApplicationSecurityTestRule's
> getPermissionToken() method to obtain some tokens based on Allowed
> operations (Read, Change and Delete) and they were each of the form
> "*Bearer
> eyJhbGciOiJSU....*". Which service actually generates tokens ?
> TenantAccessTokenSerializer
> in anubis ?
>
> Concerning 2.), The tokens I obtained failed the
> SystemSecurityEnvironment's isValidToken() method.  So how can we validate
> the obtained tokens ?
>
> Regarding 3.), I noticed that Spring MVC Test provides an interface called
> the RequestPostProcessor
> <
> https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java
> >
> which
> can be used to modify a request. I intend to use this to add a valid token
> to each MockMvc call. I wrote a method which modifies a request by
> adding a *header(ApiConstants.AUTHORIZATON_HEADER,
> myToken)* and then running each MockMvc call in the unit test with an
> object of the class holding this method.
>
> Also, you mentioned a Spring Security filter which filters requests to
> endpoints. Where exactly is this filter located ? I've been scouring anubis
> for it to no avail. I'm considering mocking the filter to permit specific
> tokens or calls go through.
>
> Your help will be greatly appreciated.
>
> At Your Service,
> Isaac Kamga.
>
> On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org> wrote:
>
> > Hey Isaac,
> >
> > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org>
> > wrote:
> > > Thanks for your very helpful feedback.
> >
> > You're very welcome.  Thank you for taking it so well.
> >
> > > Do we have to use a different approach ( possibly the documentation
> > module
> > > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE ) from
> > > synchronous ones (GET) ? This can be done later but I wanted to know
> your
> > > thoughts on this.
> >
> > Fortunately we do not.  The asynchronous calls will return an
> > ACCEPTED, and the synchronous calls will return OK.  From the point of
> > view of the documentation, and of calling them, that's the only
> > difference.  The asynchronous calls can also return BAD REQUEST for
> > any invalid values which are fast to check (where the synchronous ones
> > will return BAD REQUEST for invalid values regardless of how easy they
> > are to check.)
> >
> > The documentation module is still an open question for me.  But not
> > because of asynchronous vs synchronous calls.
> >
> > > Thanks for shedding more light on how this works. When I saw how "easy"
> > it
> > > was to do API calls, I asked myself how one could get to intercept
> > > information such as the status of a response. Building a new test
> harness
> > > that works with mockmvc can be a daunting task. I hope I can count on
> > your
> > > help when I run into frustrations.
> >
> > I'll do what I can, but I don't know mockmvc.  I've never used it,
> > partly because of this problem.
> >
> > > So far, I created this document
> > > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> > +Fineract+CN+API+Documentation>
> > > to
> > > help developers generate the asciidoc files themselves from the unit
> > tests.
> > > Would you prefer that we put this in the repository's README file or
> > leave
> > > it on confluence ?
> >
> > Let's start off with it where it is, and see whether it works by
> > trying it out there.
> >
> > You're doing good,
> >
> > Best Regards,
> > Myrle
> >
>

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hello Myrle,

Trust that you're doing great.

Following your recommendations, I intended solving the issue using a 3-step
approach;

1. Obtain token
2. Validate token
3. Add token to MockMvc call as a header.

However, I've been unable to get status different from 404 (Not Found) and
403 (Forbidden) in the MockMvc calls...so I think I'm getting at least one
of the 3 steps above wrong.

Regarding 1.), I used TenantApplicationSecurityTestRule's
getPermissionToken() method to obtain some tokens based on Allowed
operations (Read, Change and Delete) and they were each of the form "*Bearer
eyJhbGciOiJSU....*". Which service actually generates tokens ?
TenantAccessTokenSerializer
in anubis ?

Concerning 2.), The tokens I obtained failed the
SystemSecurityEnvironment's isValidToken() method.  So how can we validate
the obtained tokens ?

Regarding 3.), I noticed that Spring MVC Test provides an interface called
the RequestPostProcessor
<https://github.com/spring-projects/spring-framework/blob/master/spring-test/src/main/java/org/springframework/test/web/servlet/request/RequestPostProcessor.java>
which
can be used to modify a request. I intend to use this to add a valid token
to each MockMvc call. I wrote a method which modifies a request by
adding a *header(ApiConstants.AUTHORIZATON_HEADER,
myToken)* and then running each MockMvc call in the unit test with an
object of the class holding this method.

Also, you mentioned a Spring Security filter which filters requests to
endpoints. Where exactly is this filter located ? I've been scouring anubis
for it to no avail. I'm considering mocking the filter to permit specific
tokens or calls go through.

Your help will be greatly appreciated.

At Your Service,
Isaac Kamga.

On Tue, May 1, 2018 at 11:41 AM, Myrle Krantz <my...@apache.org> wrote:

> Hey Isaac,
>
> On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org>
> wrote:
> > Thanks for your very helpful feedback.
>
> You're very welcome.  Thank you for taking it so well.
>
> > Do we have to use a different approach ( possibly the documentation
> module
> > you earlier proposed ) for asynchronous calls (POST, PUT, DELETE ) from
> > synchronous ones (GET) ? This can be done later but I wanted to know your
> > thoughts on this.
>
> Fortunately we do not.  The asynchronous calls will return an
> ACCEPTED, and the synchronous calls will return OK.  From the point of
> view of the documentation, and of calling them, that's the only
> difference.  The asynchronous calls can also return BAD REQUEST for
> any invalid values which are fast to check (where the synchronous ones
> will return BAD REQUEST for invalid values regardless of how easy they
> are to check.)
>
> The documentation module is still an open question for me.  But not
> because of asynchronous vs synchronous calls.
>
> > Thanks for shedding more light on how this works. When I saw how "easy"
> it
> > was to do API calls, I asked myself how one could get to intercept
> > information such as the status of a response. Building a new test harness
> > that works with mockmvc can be a daunting task. I hope I can count on
> your
> > help when I run into frustrations.
>
> I'll do what I can, but I don't know mockmvc.  I've never used it,
> partly because of this problem.
>
> > So far, I created this document
> > <https://cwiki.apache.org/confluence/display/FINERACT/Apache
> +Fineract+CN+API+Documentation>
> > to
> > help developers generate the asciidoc files themselves from the unit
> tests.
> > Would you prefer that we put this in the repository's README file or
> leave
> > it on confluence ?
>
> Let's start off with it where it is, and see whether it works by
> trying it out there.
>
> You're doing good,
>
> Best Regards,
> Myrle
>

Re: Apache Fineract CN API Documentation

[Myrle Krantz <my...@apache.org>]

Hey Isaac,

On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <is...@mifos.org> wrote:
> Thanks for your very helpful feedback.

You're very welcome.  Thank you for taking it so well.

> Do we have to use a different approach ( possibly the documentation module
> you earlier proposed ) for asynchronous calls (POST, PUT, DELETE ) from
> synchronous ones (GET) ? This can be done later but I wanted to know your
> thoughts on this.

Fortunately we do not.  The asynchronous calls will return an
ACCEPTED, and the synchronous calls will return OK.  From the point of
view of the documentation, and of calling them, that's the only
difference.  The asynchronous calls can also return BAD REQUEST for
any invalid values which are fast to check (where the synchronous ones
will return BAD REQUEST for invalid values regardless of how easy they
are to check.)

The documentation module is still an open question for me.  But not
because of asynchronous vs synchronous calls.

> Thanks for shedding more light on how this works. When I saw how "easy" it
> was to do API calls, I asked myself how one could get to intercept
> information such as the status of a response. Building a new test harness
> that works with mockmvc can be a daunting task. I hope I can count on your
> help when I run into frustrations.

I'll do what I can, but I don't know mockmvc.  I've never used it,
partly because of this problem.

> So far, I created this document
> <https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation>
> to
> help developers generate the asciidoc files themselves from the unit tests.
> Would you prefer that we put this in the repository's README file or leave
> it on confluence ?

Let's start off with it where it is, and see whether it works by
trying it out there.

You're doing good,

Best Regards,
Myrle

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hi Myrle,

Thanks for your very helpful feedback.

On Mon, Apr 30, 2018 at 8:07 PM, Myrle Krantz <my...@apache.org> wrote:

> Hey Isaac,
>
> I think we're coming closer to our goal with this PR, but we still
> have some work to do.  I do like it better in the component-test
> module, though I don't think you'll want to add this to all of the
> component-tests.  Some of them really aren't suited to this approach.
>

Do we have to use a different approach ( possibly the documentation module
you earlier proposed ) for asynchronous calls (POST, PUT, DELETE ) from
synchronous ones (GET) ? This can be done later but I wanted to know your
thoughts on this.


> If I read your code correctly, you're getting a 404 Not Found, or a
> 403 out of every REST endpoint.  That doesn't surprise me because the
> endpoints are protected by a Spring Security filter which checks
> whether a JWT token was put into a header.  If the token isn't there,
> or isn't valid, then the filter throws a 403 before ever even checking
> if the endpoint exists.  The reason calling the http methods via the
> feign interface doesn't fail the same way, is because I've put a lot
> of work into setting up a valid security context via the feign
> interface for those calls.  If you look closely, you'll see there's an
> AutoUserContext which sets a thread-local variable containing the JWT
> token.  There's an anubis test artifact for generating a valid JWT
> token in the context of tests.  The feign client then has customized
> code to add an http header to the request using the content of that
> thread local.  It was coded to be as easy to use as possible, but as a
> result, it's almost invisible, and therefore not obvious for people
> trying to add another kind of client code.


> The JWT header will have to be added to the call to mockmvc, otherwise
> you'll never get a return value other than Not Found, (or invalid
> token).  The place this is done in the feign header is here:
> https://github.com/apache/fineract-cn-api/blob/develop/
> src/main/java/org/apache/fineract/cn/api/util/
> TokenedTargetInterceptor.java
>
> There's also code for adding a tenant header here:
> https://github.com/apache/fineract-cn-api/blob/develop/
> src/main/java/org/apache/fineract/cn/api/util/
> TenantedTargetInterceptor.java
>
> You'll need to create something equivalent for mockmvc, or else set
> these headers explicitly in every call.
>

Thanks for shedding more light on how this works. When I saw how "easy" it
was to do API calls, I asked myself how one could get to intercept
information such as the status of a response. Building a new test harness
that works with mockmvc can be a daunting task. I hope I can count on your
help when I run into frustrations.


> Also note:
> By adding REST calls to the end of each function, you are running the
> http calls for the test twice.  I'm not sure that's deliberate.  Maybe
> it would make more sense to create a separate test for generating
> documentation?
>

Okay, when we get a breakthrough with the right return status values, I'll
proceed with segregating tests aimed at generating documentation.


>
> As far as the documentation that is generated by the process, it's
> actually just the same information as in the test, but in a different
> form.  IMO it doesn't make sense to check that in.  It's enough to
> include the instructions for generating it in the README, or in the
> Fineract wikipedia.
>

So far, I created this document
<https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation>
to
help developers generate the asciidoc files themselves from the unit tests.
Would you prefer that we put this in the repository's README file or leave
it on confluence ?

Beyond that, I feel bad that I haven't been responding to you as
> quickly as I would like.  I'd like to reduce my response time to 36
> hours on weekdays for you, so that you don't spend so much time
> blocked on this.  I'm setting it as a goal for myself.  Gentle
> encouragement to live up to this goal is appreciated. ; o)
>

Day by day, I appreciate how complex Fineract CN is. I'm very happy that
you've set aside time to mentor me on this project. I had been groping in
the dark for months now reason why I never even thought about other
relevant concerns like architecture, etc when I saw some light with the PoC
which started generating docs. I'll make sure to discuss updates on this
thread in a gentle manner as you requested. ;-)


> Best Regards,
> Myrle
>
>
> On Fri, Apr 27, 2018 at 3:54 PM, Isaac Kamga <is...@mifos.org>
> wrote:
> > Hello everyone,
> >
> > I've made some changes to the approach for API documentation based on
> > Myrle's feedback.
> >
> > So I have reverted my recent changes to fineract-cn-customer and created
> a
> > pull request [1] for review. I am hoping that we'll get all necessary
> fixes
> > on the PR before I move on to documenting the other services.
> >
> > I have also documented the process [2] for API Documentation which
> > stipulates how a developer can generate the snippets for documentation (
> in
> > component-test's build/doc/ folder ) given that we don't want .adoc file
> > and such checked into the repository.
> >
> > I await your thoughts on this.
> >
> > [1] https://github.com/apache/fineract-cn-customer/pull/7
> > [2]
> > https://cwiki.apache.org/confluence/display/FINERACT/
> Apache+Fineract+CN+API+Documentation
> >
> >
> > On Wed, Apr 25, 2018 at 6:09 PM, Isaac Kamga <is...@mifos.org>
> wrote:
> >
> >> Hello Myrle,
> >>
> >> I've done some tinkering and Spring REST Docs can indeed get the
> snippets
> >> generated for documentation in the component-test module. At least, that
> >> ensures that there's no need for an architectural change and the service
> >> module doesn't depend on the component-test module as Markus advised.
> >>
> >> I think there are still other concerns which you highlighted;
> >>
> >> 1. Checking in generated documentation : Should we leave them in
> >> component-test's build folder (which is ignored by git) and rather
> document
> >> the process of generating the snippets ?
> >>
> >> 2. Creating a documentation module : Do we still need to try this out ?
> >> This module will import the service and component-test modules.
> >>
> >> 3. MockMvc vs Spring Fox: Were you concerned about the security of
> MockMvc
> >> ?
> >>
> >> I'd like to have this discussed here so that we don't proceed with
> >> approaches to solving the problem which aren't worthwhile. I had earlier
> >> assumed that a mention on the Quarter 1 board report about my work on
> API
> >> documentation would have sufficed.
> >>
> >> If you're okay with the API documentation occurring in the
> component-test
> >> module, it may be okay for me to revert the commits I made to the
> >> repositories and submit a Pull request which you'll review and merge.
> >>
> >> At Your Service,
> >> Isaac Kamga.
> >>
> >> On Wed, Apr 25, 2018 at 11:53 AM, Isaac Kamga <is...@mifos.org>
> >> wrote:
> >>
> >>> Hi Myrle,
> >>>
> >>> Thanks for your elaborate feedback and corrections.
> >>>
> >>> On Wed, Apr 25, 2018 at 9:10 AM, Myrle Krantz <my...@apache.org>
> wrote:
> >>>
> >>>> Hey Isaac,
> >>>>
> >>>> I've looked at your changes in customer and I've found several
> >>>> problems with them:
> >>>>
> >>>> 1.) You've copied all the component tests out of the component test
> >>>> module into the service module.  This means that identical tests will
> >>>> have to be maintained in two places.  Because people aren't very good
> >>>> at keeping code in sync, you can be certain that these tests will
> >>>> diverge from each other a little more each time someone makes a
> >>>> change, and contributors (myself included) won't know which tests are
> >>>> authoritative.
> >>>
> >>>
> >>>> 2.) You've removed the Apache license header from at least one file.
> >>>> I added the Apache license header to the build files very recently, as
> >>>> one step towards making the code releasable.  We can't release the
> >>>> code without the ASF license headers.
> >>>>
> >>>
> >>> Ouch ! My bad. I would have left this commit as a PR for review first.
> >>>
> >>>
> >>>> 3.) I'm assuming the documentation is generated?  Do we really want to
> >>>> check in generated documentation?  And where is the process documented
> >>>> for generating the documentation?
> >>>>
> >>>
> >>> By default, the Spring REST Docs tool outputs documentation in the
> >>> service's build folder ( which is ignored by git ), so I placed them in
> >>> service/src/doc so they can be viewed.
> >>>
> >>>
> >>>>
> >>>> 4.) You added a compile dependency from service to test.  The service
> >>>> should not depend on test.  It should be possible to make changes and
> >>>> add environment variables and etc to the test repository without even
> >>>> thinking about whether a change might break production code or turn on
> >>>> test-configurations which weaken security in production code.
> >>>>
> >>>> In general dependencies between modules must be 1-way, or else
> >>>> compilation is difficult or impossible.  Component-tests should depend
> >>>> on service.  Service should not depend on component-test.  Markus
> >>>> mentioned this when you asked (2) You might ask, why are component
> >>>> tests a separate module? There are several reasons:
> >>>>
> >>>
> >>> I was concerned about duplicating the component-tests' tests in the
> >>> service module and asked about how to avoid the duplication for which
> I had
> >>> no feedback.(2)
> >>>
> >>>
> >>>> * We may wish to release the service and api modules and not release
> >>>> the component-test module.  This opens up some possibilities for the
> >>>> tests that would otherwise be closed off by ASF licensing
> >>>> requirements.
> >>>> * Keeping the code seperate helps contributors keep the concerns of
> >>>> testing and the concern of functionality separate in their thought
> >>>> processes.  Putting testing code in services in other projects has
> >>>> resulted in poor code or even major security vulnerabilities.  It's
> >>>> important here to think about solutions and their trade-offs carefully
> >>>> rather than just slapping things together until they "work" and
> >>>> calling it a day.
> >>>> * One of the things I hope to accomplish in the future is versioned
> >>>> component tests to protect against backwards incompatible changes
> >>>> which can't be detected via signature checking.  We can't implement
> >>>> that plan if the tests become entangled with the source code.
> >>>>
> >>>> As a result I think we need to completely rethink the approach to
> >>>> documentation that you've taken here.  Some alternatives we should
> >>>> consider:
> >>>> * Move mockMVC into component test and out of service.  Why did you
> >>>> put the documentation and component test code in service in the first
> >>>> place?
> >>>> * Create a separate documentation module which imports code from
> >>>> component-test and service.
> >>>> * Using Spring Fox instead of MockMVC.  When I originally evaluated
> >>>> REST documentation approaches, it was exactly this mixing of other
> >>>> concerns into testing that caused me to reject MockMVC in the first
> >>>> place.  Tutorials make good tests but there are many, many good tests
> >>>> which make terrible documentation.
> >>>>
> >>>
> >>> I'm okay with the approach to documentation being rethought.
> >>>
> >>>
> >>>>
> >>>> The use of MockMVC came up a few months ago when a potential GSoC
> >>>> intern suggested it.  I had thought, based on your response, that you
> >>>> understood why it doesn't work well with our architecture. (1) Which
> >>>> is why I didn't respond to that thread myself.  What changed?
> >>>>
> >>>> In general, when making architectural changes which change the pattern
> >>>> of all of the services it's not a good idea to just dump them into all
> >>>> the services and then ask for feedback.  You create a lot of
> >>>> unnecessary work for yourself and for your code reviewer.  A better
> >>>> approach is to make the change in the fineract-cn-template project
> >>>> first and then ask for feedback.  Better still would be to engage a
> >>>> discussion on the mailing list before doing a major architectural
> >>>> change like this.  If I had known you were working on this, I could
> >>>> have shared my thoughts before you started.
> >>>>
> >>>
> >>> I'm sorry I didn't open a discussion here about documenting the APIs.
> >>> I'm hoping we'll continue that discussion on this thread and fix the
> >>> mistakes I made.
> >>>
> >>>>
> >>>> Best Regards,
> >>>> Myrle
> >>>>
> >>>> 1.) https://lists.apache.org/thread.html/cc23a47229c262afbb6e474
> >>>> 9b7eec3117d084f84144877d59098713d@%3Cdev.fineract.apache.org%3E
> >>>> 2.) https://lists.apache.org/thread.html/d0fbdb5b21b916cc8dd3c2a
> >>>> 5061d3e90aa554bb74b63f8deabe69fe6@%3Cdev.fineract.apache.org%3E
> >>>
> >>>
> >>> At Your Service,
> >>> Isaac Kamga.
> >>>
> >>>>
> >>>>
> >>>> On Mon, Apr 23, 2018 at 8:42 PM, Isaac Kamga <is...@mifos.org>
> >>>> wrote:
> >>>> > Hello everyone,
> >>>> >
> >>>> > Trust that you're doing great and congratulations to our recently
> >>>> selected
> >>>> > GSoC 2018 students.
> >>>> >
> >>>> > As you may have observed from Gitbox notifications, I have used the
> >>>> MockMvc
> >>>> > flavour of Spring Rest Docs <https://projects.spring.io/sp
> >>>> ring-restdocs/> to
> >>>> > document the APIs for most Fineract CN domain services viz identity,
> >>>> > office, customer, group, accounting, deposit, payroll and teller,
> >>>> created
> >>>> > and merged pull requests. There were failing tests in portfolio (
> as I
> >>>> > earlier highlighted last week on the list ) and so snippets weren't
> >>>> > generated to be used for documentation.
> >>>> >
> >>>> > After updating the affected repositories, you can view the
> >>>> documentation
> >>>> > for each of the services by opening the
> >>>> > service/src/doc/html5/html5/api-docs.html file.
> >>>> >
> >>>> > I happily await your feedback and enhancements.
> >>>> >
> >>>> > At Your Service,
> >>>> > Isaac Kamga.
> >>>>
> >>>
> >>>
> >>
>

Re: Apache Fineract CN API Documentation

[Myrle Krantz <my...@apache.org>]

Hey Isaac,

I think we're coming closer to our goal with this PR, but we still
have some work to do.  I do like it better in the component-test
module, though I don't think you'll want to add this to all of the
component-tests.  Some of them really aren't suited to this approach.

If I read your code correctly, you're getting a 404 Not Found, or a
403 out of every REST endpoint.  That doesn't surprise me because the
endpoints are protected by a Spring Security filter which checks
whether a JWT token was put into a header.  If the token isn't there,
or isn't valid, then the filter throws a 403 before ever even checking
if the endpoint exists.  The reason calling the http methods via the
feign interface doesn't fail the same way, is because I've put a lot
of work into setting up a valid security context via the feign
interface for those calls.  If you look closely, you'll see there's an
AutoUserContext which sets a thread-local variable containing the JWT
token.  There's an anubis test artifact for generating a valid JWT
token in the context of tests.  The feign client then has customized
code to add an http header to the request using the content of that
thread local.  It was coded to be as easy to use as possible, but as a
result, it's almost invisible, and therefore not obvious for people
trying to add another kind of client code.

The JWT header will have to be added to the call to mockmvc, otherwise
you'll never get a return value other than Not Found, (or invalid
token).  The place this is done in the feign header is here:
https://github.com/apache/fineract-cn-api/blob/develop/src/main/java/org/apache/fineract/cn/api/util/TokenedTargetInterceptor.java

There's also code for adding a tenant header here:
https://github.com/apache/fineract-cn-api/blob/develop/src/main/java/org/apache/fineract/cn/api/util/TenantedTargetInterceptor.java

You'll need to create something equivalent for mockmvc, or else set
these headers explicitly in every call.

Also note:
By adding REST calls to the end of each function, you are running the
http calls for the test twice.  I'm not sure that's deliberate.  Maybe
it would make more sense to create a separate test for generating
documentation?

As far as the documentation that is generated by the process, it's
actually just the same information as in the test, but in a different
form.  IMO it doesn't make sense to check that in.  It's enough to
include the instructions for generating it in the README, or in the
Fineract wikipedia.

Beyond that, I feel bad that I haven't been responding to you as
quickly as I would like.  I'd like to reduce my response time to 36
hours on weekdays for you, so that you don't spend so much time
blocked on this.  I'm setting it as a goal for myself.  Gentle
encouragement to live up to this goal is appreciated. ; o)

Best Regards,
Myrle


On Fri, Apr 27, 2018 at 3:54 PM, Isaac Kamga <is...@mifos.org> wrote:
> Hello everyone,
>
> I've made some changes to the approach for API documentation based on
> Myrle's feedback.
>
> So I have reverted my recent changes to fineract-cn-customer and created a
> pull request [1] for review. I am hoping that we'll get all necessary fixes
> on the PR before I move on to documenting the other services.
>
> I have also documented the process [2] for API Documentation which
> stipulates how a developer can generate the snippets for documentation ( in
> component-test's build/doc/ folder ) given that we don't want .adoc file
> and such checked into the repository.
>
> I await your thoughts on this.
>
> [1] https://github.com/apache/fineract-cn-customer/pull/7
> [2]
> https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation
>
>
> On Wed, Apr 25, 2018 at 6:09 PM, Isaac Kamga <is...@mifos.org> wrote:
>
>> Hello Myrle,
>>
>> I've done some tinkering and Spring REST Docs can indeed get the snippets
>> generated for documentation in the component-test module. At least, that
>> ensures that there's no need for an architectural change and the service
>> module doesn't depend on the component-test module as Markus advised.
>>
>> I think there are still other concerns which you highlighted;
>>
>> 1. Checking in generated documentation : Should we leave them in
>> component-test's build folder (which is ignored by git) and rather document
>> the process of generating the snippets ?
>>
>> 2. Creating a documentation module : Do we still need to try this out ?
>> This module will import the service and component-test modules.
>>
>> 3. MockMvc vs Spring Fox: Were you concerned about the security of MockMvc
>> ?
>>
>> I'd like to have this discussed here so that we don't proceed with
>> approaches to solving the problem which aren't worthwhile. I had earlier
>> assumed that a mention on the Quarter 1 board report about my work on API
>> documentation would have sufficed.
>>
>> If you're okay with the API documentation occurring in the component-test
>> module, it may be okay for me to revert the commits I made to the
>> repositories and submit a Pull request which you'll review and merge.
>>
>> At Your Service,
>> Isaac Kamga.
>>
>> On Wed, Apr 25, 2018 at 11:53 AM, Isaac Kamga <is...@mifos.org>
>> wrote:
>>
>>> Hi Myrle,
>>>
>>> Thanks for your elaborate feedback and corrections.
>>>
>>> On Wed, Apr 25, 2018 at 9:10 AM, Myrle Krantz <my...@apache.org> wrote:
>>>
>>>> Hey Isaac,
>>>>
>>>> I've looked at your changes in customer and I've found several
>>>> problems with them:
>>>>
>>>> 1.) You've copied all the component tests out of the component test
>>>> module into the service module.  This means that identical tests will
>>>> have to be maintained in two places.  Because people aren't very good
>>>> at keeping code in sync, you can be certain that these tests will
>>>> diverge from each other a little more each time someone makes a
>>>> change, and contributors (myself included) won't know which tests are
>>>> authoritative.
>>>
>>>
>>>> 2.) You've removed the Apache license header from at least one file.
>>>> I added the Apache license header to the build files very recently, as
>>>> one step towards making the code releasable.  We can't release the
>>>> code without the ASF license headers.
>>>>
>>>
>>> Ouch ! My bad. I would have left this commit as a PR for review first.
>>>
>>>
>>>> 3.) I'm assuming the documentation is generated?  Do we really want to
>>>> check in generated documentation?  And where is the process documented
>>>> for generating the documentation?
>>>>
>>>
>>> By default, the Spring REST Docs tool outputs documentation in the
>>> service's build folder ( which is ignored by git ), so I placed them in
>>> service/src/doc so they can be viewed.
>>>
>>>
>>>>
>>>> 4.) You added a compile dependency from service to test.  The service
>>>> should not depend on test.  It should be possible to make changes and
>>>> add environment variables and etc to the test repository without even
>>>> thinking about whether a change might break production code or turn on
>>>> test-configurations which weaken security in production code.
>>>>
>>>> In general dependencies between modules must be 1-way, or else
>>>> compilation is difficult or impossible.  Component-tests should depend
>>>> on service.  Service should not depend on component-test.  Markus
>>>> mentioned this when you asked (2) You might ask, why are component
>>>> tests a separate module? There are several reasons:
>>>>
>>>
>>> I was concerned about duplicating the component-tests' tests in the
>>> service module and asked about how to avoid the duplication for which I had
>>> no feedback.(2)
>>>
>>>
>>>> * We may wish to release the service and api modules and not release
>>>> the component-test module.  This opens up some possibilities for the
>>>> tests that would otherwise be closed off by ASF licensing
>>>> requirements.
>>>> * Keeping the code seperate helps contributors keep the concerns of
>>>> testing and the concern of functionality separate in their thought
>>>> processes.  Putting testing code in services in other projects has
>>>> resulted in poor code or even major security vulnerabilities.  It's
>>>> important here to think about solutions and their trade-offs carefully
>>>> rather than just slapping things together until they "work" and
>>>> calling it a day.
>>>> * One of the things I hope to accomplish in the future is versioned
>>>> component tests to protect against backwards incompatible changes
>>>> which can't be detected via signature checking.  We can't implement
>>>> that plan if the tests become entangled with the source code.
>>>>
>>>> As a result I think we need to completely rethink the approach to
>>>> documentation that you've taken here.  Some alternatives we should
>>>> consider:
>>>> * Move mockMVC into component test and out of service.  Why did you
>>>> put the documentation and component test code in service in the first
>>>> place?
>>>> * Create a separate documentation module which imports code from
>>>> component-test and service.
>>>> * Using Spring Fox instead of MockMVC.  When I originally evaluated
>>>> REST documentation approaches, it was exactly this mixing of other
>>>> concerns into testing that caused me to reject MockMVC in the first
>>>> place.  Tutorials make good tests but there are many, many good tests
>>>> which make terrible documentation.
>>>>
>>>
>>> I'm okay with the approach to documentation being rethought.
>>>
>>>
>>>>
>>>> The use of MockMVC came up a few months ago when a potential GSoC
>>>> intern suggested it.  I had thought, based on your response, that you
>>>> understood why it doesn't work well with our architecture. (1) Which
>>>> is why I didn't respond to that thread myself.  What changed?
>>>>
>>>> In general, when making architectural changes which change the pattern
>>>> of all of the services it's not a good idea to just dump them into all
>>>> the services and then ask for feedback.  You create a lot of
>>>> unnecessary work for yourself and for your code reviewer.  A better
>>>> approach is to make the change in the fineract-cn-template project
>>>> first and then ask for feedback.  Better still would be to engage a
>>>> discussion on the mailing list before doing a major architectural
>>>> change like this.  If I had known you were working on this, I could
>>>> have shared my thoughts before you started.
>>>>
>>>
>>> I'm sorry I didn't open a discussion here about documenting the APIs.
>>> I'm hoping we'll continue that discussion on this thread and fix the
>>> mistakes I made.
>>>
>>>>
>>>> Best Regards,
>>>> Myrle
>>>>
>>>> 1.) https://lists.apache.org/thread.html/cc23a47229c262afbb6e474
>>>> 9b7eec3117d084f84144877d59098713d@%3Cdev.fineract.apache.org%3E
>>>> 2.) https://lists.apache.org/thread.html/d0fbdb5b21b916cc8dd3c2a
>>>> 5061d3e90aa554bb74b63f8deabe69fe6@%3Cdev.fineract.apache.org%3E
>>>
>>>
>>> At Your Service,
>>> Isaac Kamga.
>>>
>>>>
>>>>
>>>> On Mon, Apr 23, 2018 at 8:42 PM, Isaac Kamga <is...@mifos.org>
>>>> wrote:
>>>> > Hello everyone,
>>>> >
>>>> > Trust that you're doing great and congratulations to our recently
>>>> selected
>>>> > GSoC 2018 students.
>>>> >
>>>> > As you may have observed from Gitbox notifications, I have used the
>>>> MockMvc
>>>> > flavour of Spring Rest Docs <https://projects.spring.io/sp
>>>> ring-restdocs/> to
>>>> > document the APIs for most Fineract CN domain services viz identity,
>>>> > office, customer, group, accounting, deposit, payroll and teller,
>>>> created
>>>> > and merged pull requests. There were failing tests in portfolio ( as I
>>>> > earlier highlighted last week on the list ) and so snippets weren't
>>>> > generated to be used for documentation.
>>>> >
>>>> > After updating the affected repositories, you can view the
>>>> documentation
>>>> > for each of the services by opening the
>>>> > service/src/doc/html5/html5/api-docs.html file.
>>>> >
>>>> > I happily await your feedback and enhancements.
>>>> >
>>>> > At Your Service,
>>>> > Isaac Kamga.
>>>>
>>>
>>>
>>

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hello everyone,

I've made some changes to the approach for API documentation based on
Myrle's feedback.

So I have reverted my recent changes to fineract-cn-customer and created a
pull request [1] for review. I am hoping that we'll get all necessary fixes
on the PR before I move on to documenting the other services.

I have also documented the process [2] for API Documentation which
stipulates how a developer can generate the snippets for documentation ( in
component-test's build/doc/ folder ) given that we don't want .adoc file
and such checked into the repository.

I await your thoughts on this.

[1] https://github.com/apache/fineract-cn-customer/pull/7
[2]
https://cwiki.apache.org/confluence/display/FINERACT/Apache+Fineract+CN+API+Documentation


On Wed, Apr 25, 2018 at 6:09 PM, Isaac Kamga <is...@mifos.org> wrote:

> Hello Myrle,
>
> I've done some tinkering and Spring REST Docs can indeed get the snippets
> generated for documentation in the component-test module. At least, that
> ensures that there's no need for an architectural change and the service
> module doesn't depend on the component-test module as Markus advised.
>
> I think there are still other concerns which you highlighted;
>
> 1. Checking in generated documentation : Should we leave them in
> component-test's build folder (which is ignored by git) and rather document
> the process of generating the snippets ?
>
> 2. Creating a documentation module : Do we still need to try this out ?
> This module will import the service and component-test modules.
>
> 3. MockMvc vs Spring Fox: Were you concerned about the security of MockMvc
> ?
>
> I'd like to have this discussed here so that we don't proceed with
> approaches to solving the problem which aren't worthwhile. I had earlier
> assumed that a mention on the Quarter 1 board report about my work on API
> documentation would have sufficed.
>
> If you're okay with the API documentation occurring in the component-test
> module, it may be okay for me to revert the commits I made to the
> repositories and submit a Pull request which you'll review and merge.
>
> At Your Service,
> Isaac Kamga.
>
> On Wed, Apr 25, 2018 at 11:53 AM, Isaac Kamga <is...@mifos.org>
> wrote:
>
>> Hi Myrle,
>>
>> Thanks for your elaborate feedback and corrections.
>>
>> On Wed, Apr 25, 2018 at 9:10 AM, Myrle Krantz <my...@apache.org> wrote:
>>
>>> Hey Isaac,
>>>
>>> I've looked at your changes in customer and I've found several
>>> problems with them:
>>>
>>> 1.) You've copied all the component tests out of the component test
>>> module into the service module.  This means that identical tests will
>>> have to be maintained in two places.  Because people aren't very good
>>> at keeping code in sync, you can be certain that these tests will
>>> diverge from each other a little more each time someone makes a
>>> change, and contributors (myself included) won't know which tests are
>>> authoritative.
>>
>>
>>> 2.) You've removed the Apache license header from at least one file.
>>> I added the Apache license header to the build files very recently, as
>>> one step towards making the code releasable.  We can't release the
>>> code without the ASF license headers.
>>>
>>
>> Ouch ! My bad. I would have left this commit as a PR for review first.
>>
>>
>>> 3.) I'm assuming the documentation is generated?  Do we really want to
>>> check in generated documentation?  And where is the process documented
>>> for generating the documentation?
>>>
>>
>> By default, the Spring REST Docs tool outputs documentation in the
>> service's build folder ( which is ignored by git ), so I placed them in
>> service/src/doc so they can be viewed.
>>
>>
>>>
>>> 4.) You added a compile dependency from service to test.  The service
>>> should not depend on test.  It should be possible to make changes and
>>> add environment variables and etc to the test repository without even
>>> thinking about whether a change might break production code or turn on
>>> test-configurations which weaken security in production code.
>>>
>>> In general dependencies between modules must be 1-way, or else
>>> compilation is difficult or impossible.  Component-tests should depend
>>> on service.  Service should not depend on component-test.  Markus
>>> mentioned this when you asked (2) You might ask, why are component
>>> tests a separate module? There are several reasons:
>>>
>>
>> I was concerned about duplicating the component-tests' tests in the
>> service module and asked about how to avoid the duplication for which I had
>> no feedback.(2)
>>
>>
>>> * We may wish to release the service and api modules and not release
>>> the component-test module.  This opens up some possibilities for the
>>> tests that would otherwise be closed off by ASF licensing
>>> requirements.
>>> * Keeping the code seperate helps contributors keep the concerns of
>>> testing and the concern of functionality separate in their thought
>>> processes.  Putting testing code in services in other projects has
>>> resulted in poor code or even major security vulnerabilities.  It's
>>> important here to think about solutions and their trade-offs carefully
>>> rather than just slapping things together until they "work" and
>>> calling it a day.
>>> * One of the things I hope to accomplish in the future is versioned
>>> component tests to protect against backwards incompatible changes
>>> which can't be detected via signature checking.  We can't implement
>>> that plan if the tests become entangled with the source code.
>>>
>>> As a result I think we need to completely rethink the approach to
>>> documentation that you've taken here.  Some alternatives we should
>>> consider:
>>> * Move mockMVC into component test and out of service.  Why did you
>>> put the documentation and component test code in service in the first
>>> place?
>>> * Create a separate documentation module which imports code from
>>> component-test and service.
>>> * Using Spring Fox instead of MockMVC.  When I originally evaluated
>>> REST documentation approaches, it was exactly this mixing of other
>>> concerns into testing that caused me to reject MockMVC in the first
>>> place.  Tutorials make good tests but there are many, many good tests
>>> which make terrible documentation.
>>>
>>
>> I'm okay with the approach to documentation being rethought.
>>
>>
>>>
>>> The use of MockMVC came up a few months ago when a potential GSoC
>>> intern suggested it.  I had thought, based on your response, that you
>>> understood why it doesn't work well with our architecture. (1) Which
>>> is why I didn't respond to that thread myself.  What changed?
>>>
>>> In general, when making architectural changes which change the pattern
>>> of all of the services it's not a good idea to just dump them into all
>>> the services and then ask for feedback.  You create a lot of
>>> unnecessary work for yourself and for your code reviewer.  A better
>>> approach is to make the change in the fineract-cn-template project
>>> first and then ask for feedback.  Better still would be to engage a
>>> discussion on the mailing list before doing a major architectural
>>> change like this.  If I had known you were working on this, I could
>>> have shared my thoughts before you started.
>>>
>>
>> I'm sorry I didn't open a discussion here about documenting the APIs.
>> I'm hoping we'll continue that discussion on this thread and fix the
>> mistakes I made.
>>
>>>
>>> Best Regards,
>>> Myrle
>>>
>>> 1.) https://lists.apache.org/thread.html/cc23a47229c262afbb6e474
>>> 9b7eec3117d084f84144877d59098713d@%3Cdev.fineract.apache.org%3E
>>> 2.) https://lists.apache.org/thread.html/d0fbdb5b21b916cc8dd3c2a
>>> 5061d3e90aa554bb74b63f8deabe69fe6@%3Cdev.fineract.apache.org%3E
>>
>>
>> At Your Service,
>> Isaac Kamga.
>>
>>>
>>>
>>> On Mon, Apr 23, 2018 at 8:42 PM, Isaac Kamga <is...@mifos.org>
>>> wrote:
>>> > Hello everyone,
>>> >
>>> > Trust that you're doing great and congratulations to our recently
>>> selected
>>> > GSoC 2018 students.
>>> >
>>> > As you may have observed from Gitbox notifications, I have used the
>>> MockMvc
>>> > flavour of Spring Rest Docs <https://projects.spring.io/sp
>>> ring-restdocs/> to
>>> > document the APIs for most Fineract CN domain services viz identity,
>>> > office, customer, group, accounting, deposit, payroll and teller,
>>> created
>>> > and merged pull requests. There were failing tests in portfolio ( as I
>>> > earlier highlighted last week on the list ) and so snippets weren't
>>> > generated to be used for documentation.
>>> >
>>> > After updating the affected repositories, you can view the
>>> documentation
>>> > for each of the services by opening the
>>> > service/src/doc/html5/html5/api-docs.html file.
>>> >
>>> > I happily await your feedback and enhancements.
>>> >
>>> > At Your Service,
>>> > Isaac Kamga.
>>>
>>
>>
>

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hello Myrle,

I've done some tinkering and Spring REST Docs can indeed get the snippets
generated for documentation in the component-test module. At least, that
ensures that there's no need for an architectural change and the service
module doesn't depend on the component-test module as Markus advised.

I think there are still other concerns which you highlighted;

1. Checking in generated documentation : Should we leave them in
component-test's build folder (which is ignored by git) and rather document
the process of generating the snippets ?

2. Creating a documentation module : Do we still need to try this out ?
This module will import the service and component-test modules.

3. MockMvc vs Spring Fox: Were you concerned about the security of MockMvc ?

I'd like to have this discussed here so that we don't proceed with
approaches to solving the problem which aren't worthwhile. I had earlier
assumed that a mention on the Quarter 1 board report about my work on API
documentation would have sufficed.

If you're okay with the API documentation occurring in the component-test
module, it may be okay for me to revert the commits I made to the
repositories and submit a Pull request which you'll review and merge.

At Your Service,
Isaac Kamga.

On Wed, Apr 25, 2018 at 11:53 AM, Isaac Kamga <is...@mifos.org> wrote:

> Hi Myrle,
>
> Thanks for your elaborate feedback and corrections.
>
> On Wed, Apr 25, 2018 at 9:10 AM, Myrle Krantz <my...@apache.org> wrote:
>
>> Hey Isaac,
>>
>> I've looked at your changes in customer and I've found several
>> problems with them:
>>
>> 1.) You've copied all the component tests out of the component test
>> module into the service module.  This means that identical tests will
>> have to be maintained in two places.  Because people aren't very good
>> at keeping code in sync, you can be certain that these tests will
>> diverge from each other a little more each time someone makes a
>> change, and contributors (myself included) won't know which tests are
>> authoritative.
>
>
>> 2.) You've removed the Apache license header from at least one file.
>> I added the Apache license header to the build files very recently, as
>> one step towards making the code releasable.  We can't release the
>> code without the ASF license headers.
>>
>
> Ouch ! My bad. I would have left this commit as a PR for review first.
>
>
>> 3.) I'm assuming the documentation is generated?  Do we really want to
>> check in generated documentation?  And where is the process documented
>> for generating the documentation?
>>
>
> By default, the Spring REST Docs tool outputs documentation in the
> service's build folder ( which is ignored by git ), so I placed them in
> service/src/doc so they can be viewed.
>
>
>>
>> 4.) You added a compile dependency from service to test.  The service
>> should not depend on test.  It should be possible to make changes and
>> add environment variables and etc to the test repository without even
>> thinking about whether a change might break production code or turn on
>> test-configurations which weaken security in production code.
>>
>> In general dependencies between modules must be 1-way, or else
>> compilation is difficult or impossible.  Component-tests should depend
>> on service.  Service should not depend on component-test.  Markus
>> mentioned this when you asked (2) You might ask, why are component
>> tests a separate module? There are several reasons:
>>
>
> I was concerned about duplicating the component-tests' tests in the
> service module and asked about how to avoid the duplication for which I had
> no feedback.(2)
>
>
>> * We may wish to release the service and api modules and not release
>> the component-test module.  This opens up some possibilities for the
>> tests that would otherwise be closed off by ASF licensing
>> requirements.
>> * Keeping the code seperate helps contributors keep the concerns of
>> testing and the concern of functionality separate in their thought
>> processes.  Putting testing code in services in other projects has
>> resulted in poor code or even major security vulnerabilities.  It's
>> important here to think about solutions and their trade-offs carefully
>> rather than just slapping things together until they "work" and
>> calling it a day.
>> * One of the things I hope to accomplish in the future is versioned
>> component tests to protect against backwards incompatible changes
>> which can't be detected via signature checking.  We can't implement
>> that plan if the tests become entangled with the source code.
>>
>> As a result I think we need to completely rethink the approach to
>> documentation that you've taken here.  Some alternatives we should
>> consider:
>> * Move mockMVC into component test and out of service.  Why did you
>> put the documentation and component test code in service in the first
>> place?
>> * Create a separate documentation module which imports code from
>> component-test and service.
>> * Using Spring Fox instead of MockMVC.  When I originally evaluated
>> REST documentation approaches, it was exactly this mixing of other
>> concerns into testing that caused me to reject MockMVC in the first
>> place.  Tutorials make good tests but there are many, many good tests
>> which make terrible documentation.
>>
>
> I'm okay with the approach to documentation being rethought.
>
>
>>
>> The use of MockMVC came up a few months ago when a potential GSoC
>> intern suggested it.  I had thought, based on your response, that you
>> understood why it doesn't work well with our architecture. (1) Which
>> is why I didn't respond to that thread myself.  What changed?
>>
>> In general, when making architectural changes which change the pattern
>> of all of the services it's not a good idea to just dump them into all
>> the services and then ask for feedback.  You create a lot of
>> unnecessary work for yourself and for your code reviewer.  A better
>> approach is to make the change in the fineract-cn-template project
>> first and then ask for feedback.  Better still would be to engage a
>> discussion on the mailing list before doing a major architectural
>> change like this.  If I had known you were working on this, I could
>> have shared my thoughts before you started.
>>
>
> I'm sorry I didn't open a discussion here about documenting the APIs.
> I'm hoping we'll continue that discussion on this thread and fix the
> mistakes I made.
>
>>
>> Best Regards,
>> Myrle
>>
>> 1.) https://lists.apache.org/thread.html/cc23a47229c262afbb6e474
>> 9b7eec3117d084f84144877d59098713d@%3Cdev.fineract.apache.org%3E
>> 2.) https://lists.apache.org/thread.html/d0fbdb5b21b916cc8dd3c2a
>> 5061d3e90aa554bb74b63f8deabe69fe6@%3Cdev.fineract.apache.org%3E
>
>
> At Your Service,
> Isaac Kamga.
>
>>
>>
>> On Mon, Apr 23, 2018 at 8:42 PM, Isaac Kamga <is...@mifos.org>
>> wrote:
>> > Hello everyone,
>> >
>> > Trust that you're doing great and congratulations to our recently
>> selected
>> > GSoC 2018 students.
>> >
>> > As you may have observed from Gitbox notifications, I have used the
>> MockMvc
>> > flavour of Spring Rest Docs <https://projects.spring.io/sp
>> ring-restdocs/> to
>> > document the APIs for most Fineract CN domain services viz identity,
>> > office, customer, group, accounting, deposit, payroll and teller,
>> created
>> > and merged pull requests. There were failing tests in portfolio ( as I
>> > earlier highlighted last week on the list ) and so snippets weren't
>> > generated to be used for documentation.
>> >
>> > After updating the affected repositories, you can view the documentation
>> > for each of the services by opening the
>> > service/src/doc/html5/html5/api-docs.html file.
>> >
>> > I happily await your feedback and enhancements.
>> >
>> > At Your Service,
>> > Isaac Kamga.
>>
>
>

Re: Apache Fineract CN API Documentation

[Isaac Kamga <is...@mifos.org>]

Hi Myrle,

Thanks for your elaborate feedback and corrections.

On Wed, Apr 25, 2018 at 9:10 AM, Myrle Krantz <my...@apache.org> wrote:

> Hey Isaac,
>
> I've looked at your changes in customer and I've found several
> problems with them:
>
> 1.) You've copied all the component tests out of the component test
> module into the service module.  This means that identical tests will
> have to be maintained in two places.  Because people aren't very good
> at keeping code in sync, you can be certain that these tests will
> diverge from each other a little more each time someone makes a
> change, and contributors (myself included) won't know which tests are
> authoritative.


> 2.) You've removed the Apache license header from at least one file.
> I added the Apache license header to the build files very recently, as
> one step towards making the code releasable.  We can't release the
> code without the ASF license headers.
>

Ouch ! My bad. I would have left this commit as a PR for review first.


> 3.) I'm assuming the documentation is generated?  Do we really want to
> check in generated documentation?  And where is the process documented
> for generating the documentation?
>

By default, the Spring REST Docs tool outputs documentation in the
service's build folder ( which is ignored by git ), so I placed them in
service/src/doc so they can be viewed.


>
> 4.) You added a compile dependency from service to test.  The service
> should not depend on test.  It should be possible to make changes and
> add environment variables and etc to the test repository without even
> thinking about whether a change might break production code or turn on
> test-configurations which weaken security in production code.
>
> In general dependencies between modules must be 1-way, or else
> compilation is difficult or impossible.  Component-tests should depend
> on service.  Service should not depend on component-test.  Markus
> mentioned this when you asked (2) You might ask, why are component
> tests a separate module? There are several reasons:
>

I was concerned about duplicating the component-tests' tests in the service
module and asked about how to avoid the duplication for which I had no
feedback.(2)


> * We may wish to release the service and api modules and not release
> the component-test module.  This opens up some possibilities for the
> tests that would otherwise be closed off by ASF licensing
> requirements.
> * Keeping the code seperate helps contributors keep the concerns of
> testing and the concern of functionality separate in their thought
> processes.  Putting testing code in services in other projects has
> resulted in poor code or even major security vulnerabilities.  It's
> important here to think about solutions and their trade-offs carefully
> rather than just slapping things together until they "work" and
> calling it a day.
> * One of the things I hope to accomplish in the future is versioned
> component tests to protect against backwards incompatible changes
> which can't be detected via signature checking.  We can't implement
> that plan if the tests become entangled with the source code.
>
> As a result I think we need to completely rethink the approach to
> documentation that you've taken here.  Some alternatives we should
> consider:
> * Move mockMVC into component test and out of service.  Why did you
> put the documentation and component test code in service in the first
> place?
> * Create a separate documentation module which imports code from
> component-test and service.
> * Using Spring Fox instead of MockMVC.  When I originally evaluated
> REST documentation approaches, it was exactly this mixing of other
> concerns into testing that caused me to reject MockMVC in the first
> place.  Tutorials make good tests but there are many, many good tests
> which make terrible documentation.
>

I'm okay with the approach to documentation being rethought.


>
> The use of MockMVC came up a few months ago when a potential GSoC
> intern suggested it.  I had thought, based on your response, that you
> understood why it doesn't work well with our architecture. (1) Which
> is why I didn't respond to that thread myself.  What changed?
>
> In general, when making architectural changes which change the pattern
> of all of the services it's not a good idea to just dump them into all
> the services and then ask for feedback.  You create a lot of
> unnecessary work for yourself and for your code reviewer.  A better
> approach is to make the change in the fineract-cn-template project
> first and then ask for feedback.  Better still would be to engage a
> discussion on the mailing list before doing a major architectural
> change like this.  If I had known you were working on this, I could
> have shared my thoughts before you started.
>

I'm sorry I didn't open a discussion here about documenting the APIs.
I'm hoping we'll continue that discussion on this thread and fix the
mistakes I made.

>
> Best Regards,
> Myrle
>
> 1.) https://lists.apache.org/thread.html/cc23a47229c262afbb6e4749b7eec3
> 117d084f84144877d59098713d@%3Cdev.fineract.apache.org%3E
> 2.) https://lists.apache.org/thread.html/d0fbdb5b21b916cc8dd3c2a5061d3e
> 90aa554bb74b63f8deabe69fe6@%3Cdev.fineract.apache.org%3E


At Your Service,
Isaac Kamga.

>
>
> On Mon, Apr 23, 2018 at 8:42 PM, Isaac Kamga <is...@mifos.org>
> wrote:
> > Hello everyone,
> >
> > Trust that you're doing great and congratulations to our recently
> selected
> > GSoC 2018 students.
> >
> > As you may have observed from Gitbox notifications, I have used the
> MockMvc
> > flavour of Spring Rest Docs <https://projects.spring.io/spring-restdocs/>
> to
> > document the APIs for most Fineract CN domain services viz identity,
> > office, customer, group, accounting, deposit, payroll and teller, created
> > and merged pull requests. There were failing tests in portfolio ( as I
> > earlier highlighted last week on the list ) and so snippets weren't
> > generated to be used for documentation.
> >
> > After updating the affected repositories, you can view the documentation
> > for each of the services by opening the
> > service/src/doc/html5/html5/api-docs.html file.
> >
> > I happily await your feedback and enhancements.
> >
> > At Your Service,
> > Isaac Kamga.
>

Re: Apache Fineract CN API Documentation

[Myrle Krantz <my...@apache.org>]

Hey Isaac,

I've looked at your changes in customer and I've found several
problems with them:

1.) You've copied all the component tests out of the component test
module into the service module.  This means that identical tests will
have to be maintained in two places.  Because people aren't very good
at keeping code in sync, you can be certain that these tests will
diverge from each other a little more each time someone makes a
change, and contributors (myself included) won't know which tests are
authoritative.

2.) You've removed the Apache license header from at least one file.
I added the Apache license header to the build files very recently, as
one step towards making the code releasable.  We can't release the
code without the ASF license headers.

3.) I'm assuming the documentation is generated?  Do we really want to
check in generated documentation?  And where is the process documented
for generating the documentation?

4.) You added a compile dependency from service to test.  The service
should not depend on test.  It should be possible to make changes and
add environment variables and etc to the test repository without even
thinking about whether a change might break production code or turn on
test-configurations which weaken security in production code.

In general dependencies between modules must be 1-way, or else
compilation is difficult or impossible.  Component-tests should depend
on service.  Service should not depend on component-test.  Markus
mentioned this when you asked (2) You might ask, why are component
tests a separate module? There are several reasons:

* We may wish to release the service and api modules and not release
the component-test module.  This opens up some possibilities for the
tests that would otherwise be closed off by ASF licensing
requirements.
* Keeping the code seperate helps contributors keep the concerns of
testing and the concern of functionality separate in their thought
processes.  Putting testing code in services in other projects has
resulted in poor code or even major security vulnerabilities.  It's
important here to think about solutions and their trade-offs carefully
rather than just slapping things together until they "work" and
calling it a day.
* One of the things I hope to accomplish in the future is versioned
component tests to protect against backwards incompatible changes
which can't be detected via signature checking.  We can't implement
that plan if the tests become entangled with the source code.

As a result I think we need to completely rethink the approach to
documentation that you've taken here.  Some alternatives we should
consider:
* Move mockMVC into component test and out of service.  Why did you
put the documentation and component test code in service in the first
place?
* Create a separate documentation module which imports code from
component-test and service.
* Using Spring Fox instead of MockMVC.  When I originally evaluated
REST documentation approaches, it was exactly this mixing of other
concerns into testing that caused me to reject MockMVC in the first
place.  Tutorials make good tests but there are many, many good tests
which make terrible documentation.

The use of MockMVC came up a few months ago when a potential GSoC
intern suggested it.  I had thought, based on your response, that you
understood why it doesn't work well with our architecture. (1) Which
is why I didn't respond to that thread myself.  What changed?

In general, when making architectural changes which change the pattern
of all of the services it's not a good idea to just dump them into all
the services and then ask for feedback.  You create a lot of
unnecessary work for yourself and for your code reviewer.  A better
approach is to make the change in the fineract-cn-template project
first and then ask for feedback.  Better still would be to engage a
discussion on the mailing list before doing a major architectural
change like this.  If I had known you were working on this, I could
have shared my thoughts before you started.

Best Regards,
Myrle

1.) https://lists.apache.org/thread.html/cc23a47229c262afbb6e4749b7eec3117d084f84144877d59098713d@%3Cdev.fineract.apache.org%3E
2.) https://lists.apache.org/thread.html/d0fbdb5b21b916cc8dd3c2a5061d3e90aa554bb74b63f8deabe69fe6@%3Cdev.fineract.apache.org%3E

On Mon, Apr 23, 2018 at 8:42 PM, Isaac Kamga <is...@mifos.org> wrote:
> Hello everyone,
>
> Trust that you're doing great and congratulations to our recently selected
> GSoC 2018 students.
>
> As you may have observed from Gitbox notifications, I have used the MockMvc
> flavour of Spring Rest Docs <https://projects.spring.io/spring-restdocs/> to
> document the APIs for most Fineract CN domain services viz identity,
> office, customer, group, accounting, deposit, payroll and teller, created
> and merged pull requests. There were failing tests in portfolio ( as I
> earlier highlighted last week on the list ) and so snippets weren't
> generated to be used for documentation.
>
> After updating the affected repositories, you can view the documentation
> for each of the services by opening the
> service/src/doc/html5/html5/api-docs.html file.
>
> I happily await your feedback and enhancements.
>
> At Your Service,
> Isaac Kamga.