Re: Apache Fineract CN API Documentation
Thanks for your email.
Yes, I think the API documentation can be an important part of the Apache
Fineract CN project.
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,
On Fri, May 25, 2018 at 10:42 PM James Dailey <jamespdailey@xxxxxxxxx>
> 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 <
> 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.
> 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 ?
> Similarly, there is a reference to how generic URI's are formed with a
> given example:
> 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. )
> - James
> On Thu, May 24, 2018 at 6:00 AM Isaac Kamga <isaac.kamga@xxxxxxxxx> wrote:
> > Hello Myrle,
> > Trust that you're doing great.
> > Following your recommendations, I intended solving the issue using a
> > 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)
> > 403 (Forbidden) in the MockMvc calls...so I think I'm getting at least
> > 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
> > the obtained tokens ?
> > Regarding 3.), I noticed that Spring MVC Test provides an interface
> > the RequestPostProcessor
> > <
> > >
> > which
> > can be used to modify a request. I intend to use this to add a valid
> > 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
> > 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 <myrle@xxxxxxxxxx> wrote:
> > > Hey Isaac,
> > >
> > > On Tue, May 1, 2018 at 11:17 AM, Isaac Kamga <isaac.kamga@xxxxxxxxx>
> > > 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 )
> > > > 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
> > > 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
> > >