You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@fineract.apache.org by Awasum Yannick <aw...@apache.org> on 2018/09/03 12:41:20 UTC
Re: Apache Fineract CN API Documentation
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
Posted by 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
> >> >> > >
> >> >> >
> >> >>
> >> >
> >>
> >
>