[Mifos-developer] Mifos X API - A call for feedback from developers in the community

[John Woodlock]

Hi all,

API Doc
https://ec2-46-137-62-163.eu-west-1.compute.amazonaws.com:8443/api-docs/apiLive.htm

We've just completed our review of the Mifos X API (for Individual
Lending) and the above link is its 'interactive' result.

We've done a bit of a study on API best practices so, if we've done a
reasonable job, the API should greatly facilitate the
ease-of-building of mobile and browser apps on top of it... in
whatever languages are best suited to mobile, browser and indeed any
other application development.

It's probably a lot better to use it than talk about it as it should
talk for itself. It is full of live examples that help you learn about
the API right from your browser. Any feedback will be well-received
and any queries responded to.

John

Notes:
The API and docs are in a temporary place at the moment until they are
moved to a more permanent home on a Mifos server.
Because of this your browser will show you a warning message the first
time you use an API example. This is because we have a self-signed
SSL certificate rather than a real one.
Just choose to Proceed Anyway or Store Permanently or whatever your
browser asks you to do to carry on.

When you are asked for a username/password
Username: super1
Password: demo

We've moved the Individual Lending application (which is the first
client app for the API). We still have a small tech difficulty with
running the individual lending app in IE... so avoid IE if you can for
now.

Individual Lending application link
https://ec2-46-137-62-163.eu-west-1.compute.amazonaws.com:8443/mifosng-individual-lending-app

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
Mifos-developer mailing list
mifos-d...@lists.sourceforge.net
Unsubscribe or change settings at:
https://lists.sourceforge.net/lists/listinfo/mifos-developer

[Ed Cable]

Some feedback from Soham to pass along:

On Mon, Jun 25, 2012 at 7:48 AM, Soham Dhakal  wrote:

Hi Ed
I took a (somewhat quick) look at the Mifos X API, and overall i am
very impressed. You guys have used a good technology to expose the
interactions with Mifos, which will enable developers to quickly
utilize it to develop/extend their own custom application. As the
mobile technology is the future for places like Nepal (low energy cost
for the end user), I can see apps being developed to be deployed
rapidly and addition of features.

This API overcomes the one of the biggest hurdle in deploying Mifos to
country like Nepal, where there is a crippling shortage of electricity
in areas where MFI's function. By giving these APIs , the client
interaction platform can be built around devices that use very little
energy.

As i get more time i will look more into it and keep u updated.

Thanks
Soham

mifos-developer@lists.sourceforge.net

[Sam Birney]

Mifos X sounds really exciting! 

The approach of building solid APIs that can support different client app implementations sounds right on.

In past, the functionality of Mifos has often been too closely coupled with the UI and this seems like the best strategy for truly separating the general functionality of an MIS from the various possible extensions and UIs that might be useful.

I'm glad to know there are some stellar developers working on it, best wishes and I look forward to seeing the iterative progress.

[Keith Woodlock]

Thank you Sam, Soham and to those that got back to ed privately off
list (conflux, ben, hugo)

> The approach of building solid APIs that can support different client app
> implementations sounds right on.
>
> In past, the functionality of Mifos has often been too closely coupled with
> the UI and this seems like the best strategy for truly separating the
> general functionality of an MIS from the various possible extensions and UIs
> that might be useful.

Thats exactly the problem (widely different requirements/needs across
MFIs) we want to solve (with platform + app approach) that the
existing mifos product never really solved.

Going foward we will show how cheap/easy/light applications can be
when much of the complexity of microfinance operations is codified
behind a clean API. It simply becomes a problem of evolving the
platform to cater for the various microfinance methodologies/models
out there which is something that is very achieveable in the near
future.

There is a demo/talk of the existing API happening today at 3:30
(Ireland time) should anyone want to listen in.

regards,
Keith.

>>> mifos-d...@lists.sourceforge.net

>>> Unsubscribe or change settings at:
>>> https://lists.sourceforge.net/lists/listinfo/mifos-developer
>
>

> ------------------------------------------------------------------------------
> Live Security Virtual Conference
> Exclusive live event will cover all the ways today's security and
> threat landscape has changed and how IT managers can respond. Discussions
> will include endpoint security, mobile security and the latest in malware
> threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
> Mifos-developer mailing list

> mifos-d...@lists.sourceforge.net

> Unsubscribe or change settings at:
> https://lists.sourceforge.net/lists/listinfo/mifos-developer

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
Mifos-developer mailing list

mifos-d...@lists.sourceforge.net

[Terry Wong]

Hi Everyone,

I've been mostly lurking for a while, but was thrilled to hear from Ed about the work on the new Mifos X API. John and Keith deserve a huge round of praise for putting together a clear and useful implementation, unleashing the power of Mifos from the UI and allowing us finally, after 7 years, to realize Mifos as a multimodal platform for Microfinance. Here are some thoughts I thought I might offer after some review of the API and docs:


*Good use of API docs and sample instance*
It looks like docco or a similar tool's output, and really is quite clear. The examples are easy to follow, and it really helps that RESTClient or similar browser tools can be used to experiment. The provision of a sample instance is great, and I dare say we should try to keep one up and running for anyone at a potential customer site wanting to "kick the tires".

*Maybe make a reset facility for the sample instance?*
I was experimenting with creating roles, and then couldn't delete them. Not really a big deal if you periodically refresh the db to a pristine state.

*Should the UPDATE Additional Field example's URL be escaped in the docs?*
I'm referring to the toward the end of this:

POST https://ec2-46-137-62-163.eu-west-1.compute.amazonaws.com:8443/mifosng-provider/api/v1/additionalfields/portfolio_client/Additional Information/2

*Perhaps Reports Data as attributes?*
I can see returning headers and then data in rows, but perhaps include an option to return the report data as objects with attributes? Like so:

{
"Report Data": [
{
"Branch": "Demo MFI Head Office",
"Name": "O'Meara, Patrick",
"Joining Date": "2009-01-04"
},
{
"Branch": "Demo MFI Head Office",
"Nane": "O'Meara, Dennis",
"Joining Date": "2009-01-04"
}
]
}

*Administrative Functions*
It looks like Admin functions are still up for discussion, meaning there are not any functions beyond listing permissions to support an admin app. I tried, for example, to create a role and then delete it, but of course this version doesn't support it. I'm not insisting that future versions should do so, but perhaps it would be fruitful to discuss the merits of a more developed admin API.

*Consider support for requests of multiple instances of an object to ease slow or intermittent connections and allow offline mode*
Especially in mobile applications, there is a need to minimize the costs of setup and takedown of connections. The API easily supports requests for single objects, and can handle a demo application for an MFI field officer application on a handset. A specific use case to consider---not too uncommon in some areas---is a intermittently connected user because of poor tower coverage---who may need to download a set of records, cache them on the device, transact business like disbursals and collections, and then upload those changes when back online (this situation was described as "offline Mifos").

What's more is that the connections are still 2G, the handset is an USD 80 Android handset with a lightly powered CPU, and thus setup and takedown of an HTTP session is actually expensive. In this case, supporting the ability to request multiple records with one HTTP connection might be desirable. Perhaps consider:

GET https://ec2-46-137-62-163.eu-west-1.compute.amazonaws.com:8443/mifosng-provider/api/v1/clients?ids=18,20,31,93

or (more ugly and I'm not sure good):

GET https://ec2-46-137-62-163.eu-west-1.compute.amazonaws.com:8443/mifosng-provider/api/v1/clients/18,20,31,93

and

GET https://ec2-46-137-62-163.eu-west-1.compute.amazonaws.com:8443/mifosng-provider/api/v1/loans?ids=185,203,312,933

or (again more ugly and I'm not sure good):

https://ec2-46-137-62-163.eu-west-1.compute.amazonaws.com:8443/mifosng-provider/api/v1/loans/185,203,312,933

One might even provide a pre-computed bundle for such a situation as a report, but in a more attribute-rich (as opposed to row-oriented) notation as described above for the report data:

GET https://ec2-46-137-62-163.eu-west-1.compute.amazonaws.com:8443/mifosng-provider/api/v1/user/29941/daily-bundle
GET https://ec2-46-137-62-163.eu-west-1.compute.amazonaws.com:8443/mifosng-provider/api/v1/user/29941/daily-bundle?date=2012-07-15

It is absolutely fair to regard these suggestions as optimizations. :-)

*Language Bindings*
Without a credible RESTful service implementation, it would be silly to even mention language bindings, so now here we are! Perhaps the project might consider soliciting bindings contributions from developers for at least: JavaScript and Android.

*Reference Apps?*
What reference apps will the team be providing to showcase some possible uses of the API?


Great job, and many thanks!
Terry.

[John Woodlock]

Thanks to everyone (whether you posted to the list or privately) for
the feedback to the initial Mifos X API. Some people really gave it a
pretty thorough look-over.

Terry's post covers much of the feedback we received so I'll just give
a few responses to that post.

The intention is to keep a 'demo' site available so that people can
test out things or build an app or a bit of an app without having to
install the platform locally (especially if people aren't set up for
java or tomcat and they shouldn't have to be). We are expecting to
move it to a mifos domain name at some point rather than the current
ec2 instance. Also, we're currently converting our Individual Lending
app so that it runs completely off html/javascript (currently it is a
java app). This should bring it to a wider audience and be a better
source of example code for app development.

Reseting the db is a good idea :) I played around with adding and
changing roles myself and had to restore... so we need to do something
here.

Terry: "Should the UPDATE Additional Field example's URL be escaped in
the docs?" - no, it shouldn't... I think its a browser thing... it was
fine for me using Firefox, but I got the same "break" when copying and
pasting from Chrome.

Good spot on the current way report data is returned. There certainly
can be a more normal JSON option as you showed (i.e. Its on the
roadmap). There is 'method in the madness' though as the format
currently returned (a generic resultset) fits nicely in with JQuery
Data Tables which we use for generic screen based reporting in the
individual lending app. As it happens 'a report' is also one of the
ways we use to extend the usefulness of the API beyond what is coded.
This is because SQL can be run to get arbitary data with arbitary
rules e.g. for building MFI specific pages or for handling condition
checking workflow variations. Anyhow, it makes even more sense for
these uses to provide the JSON option you suggested.

It is very true that we didn't build out a number of Admin type
functions (around permissions but also around reports and additional
data). This is only because we didn't need to do so first off but
have them 'on the roadmap' for sure.

There absolutely will be more 'search' functionality around clients
and loans like you suggest as there is a need to extract and import
'bulk' data and also to limit the data returned to certain conditions.
In addition to this the 'report' functionality currently provides a
way of getting arbitary data back based on setting up the report sql
(whether using the current resultset output or the normal object
output). Even doing some specific 'bulk' optimisations is absolutely
fine... mainly cos its easy to do so and we should do it if it makes
life easier (besides offline uses many MFIs import repayments). We
wanted to provide a platform that you can get data in and out of
easily... and that requires providing a number of methods... we're not
fully finished with that yet and of course some things will be
implemented as the need arises for them rather than upfront.

I don't have a good understanding on "language binding" so I'll leave
that to others to comment on.

Currently, as mentioned before, we have an Individual Lending
(browser) app... which is soon to be totally javascript. We'll send
out a post to the dev list when that's ready. So that's just the start
but obviously we want more apps to be built and the API extended.
We're keen to extend the API so it covers other microfinance
methodogies.


John

[Van Mittal-Henkle]

Bravo to John, Keith and others have contributed to the Mifox X API effort!

It is a beautiful thing to behold.  In particular the structure of the URLs for the API seems very intuitive and simple which is great.  Also the documentation is detailed and well organized.

I look forward to delving more deeply into the API as others here have, but I can say after reading though all the docs that I'm impressed.

Keep up the good work!

Cheers,
Van