Mifos Batch API

Google Summer of Code

Google Summer of code

Google Summer of Code is a global program organized by Google that offers student developers stipends to write code for various open source software projects.

Accepted student applicants are paired with a mentor or mentors from the participating projects, thus gaining exposure to real-world software development scenarios and workflows.

Mifos

Mifos is a US-based non-profit initiative that stewards the global community that builds the Mifos X platform – an open technology platform for financial inclusion used by financial services providers worldwide, supported by a network of certified local partners and maintained and extended by a global team of volunteers.

 

Mifos Batch API

  • Allows passing instructions for several operations in a single HTTP request
  • Input consists of logical HTTP requests represented as JSON array
  • Returns a JSON array of logical HTTP responses

Why do we need a Batch API?

  • Reduces Network Load by clubbing together multiple HTTP requests
  • Reduces overall Latency by a huge factor
  • Reduces wastage of Server Resources
  • Handles dependent requests
  • Provides much efficient syncing for mobile and offline systems

Features

  • Customization
  • Extendable
  • Dependency Injection
  • Allows all requests to be handled as a single transaction using enclosingTransaction parameter

Functional Structure

Client

HTTP Request ( JSON Array )

HTTP Response (JSON Array)

Batch API

Mifos API

Individual Requests

Individual Responses

UML Sequence Diagram

Sequence Flow

  1. BatchApiResource takes a JSON Array as input
  2. BatchApiService takes out individual requests
  3. CommandStrategy forwards individual requests to base API using the HTTP "method" and "relativeUrl"
  4. BatchApiService consolidates all responses/errors in response JSON Array 
  5. BatchApiResource returns the final response array to client

API EndPoints

Batch API only accepts a HTTP JSON request and responds with a JSON object as output.

 

BatchRequest and BatchResponse classes provides objects for input and output to and from the API.

 

Both the requests and responses are in the form of JSON Array, where each element represents an individual HTTP Request.

Request Fields

  • requestId - unique Id of individual request

  • relativeUrl - resource url relative to base url

  • method - HTTP Request Methods(GET, POST, etc.)

  • headers - HTTP Headers

  • reference - requestId of parent request

  • body - HTTP request Body

Response Fields

  • requestId - identifies individual input request

  • statusCode - HTTP Status Code (200, 500, etc.)

  • headers - optional headers of HTTP Response

  • body - HTTP Body of output response

 

Sample Request/Response

[
  {
    "requestId" : 1,
    "relativeUrl" : "clients",
    "method" : "POST",
    "headers": [{"name": "Content-type", "value": "text/html"}, {"name": "X-Mifos-Platform-TenantId", "value": "text/html"}],   
    "body" : "{ \"officeId\": 1, \"firstname\": \"Petra\", \"lastname\": \"Yton\", \"externalId\": \"76YYP7\",  \"dateFormat\": \"dd MMMM yyyy\", \"locale\": \"en\", \"active\": true, \"activationDate\": \"04 March 2009\",
    \"submittedOnDate\": \"04 March 2009\", \"savingsProductId\" : 1 } "
  },
  { 
    "requestId" : 2,
    "relativeUrl" : "loans",
    "method" : "POST",   
    "headers":  [{"name": "Content-type", "value": "text/html"}],   
    "reference": 1,
    "body" : "{ \"clientId\" : \"$.clientId\", \"productId\" : 1}"
  },
  {
    "requestId" : 3,
    "method" : "POST",
    "relativeUrl" : "clients",
    "headers":  [{"name": "Content-type", "value": "text/html"}],
    "body" : "{ \"officeId\": 1, \"fullname\": \"Pocahontas\", ... }"
  },
  {
    "requestId" : 4,
    "method" : "POST",
    "relativeUrl" : "savingsaccount",
    "headers":  [{"name": "Content-type", "value": "text/html"}],
    "reference": 3,
    "body" : "{ \"clientId\" : \"$.clientId\", \"productId\" : 1, ...}"
  }
]

[
  {
    "requestId" : 1,
    "statusCode" : 201,
    "headers" : [
      {
        "name" : "Content-Type",
        "value" : "application/json; charset=UTF-8"
      }
    ],
    "body" : "{ \"officeId\": 1, \"clientId\": 1, ...}"
  },
  {
    "requestId" : 2,
    "statusCode" : 201,
    "headers" : [
      {
        "name" : "Content-Type",
        "value" : "application/json; charset=UTF-8"
      }
    ],
    "body" : "{ \"officeId\": 1, \"clientId\": 1, \"loanId\": 1, ...}"
  },
  {
    "requestId" : 3,
    "statusCode" : 201,
    "headers" : [
      {
        "name" : "Content-Type",
        "value" : "application/json; charset=UTF-8"
      }
    ],
    "body" : "{ \"officeId\": 1, \"clientId\": 2, ...}"
  },
  {
    "requestId" : 4,
    "statusCode" : 201,
    "headers" : [
      {
        "name" : "Content-Type",
        "value" : "application/json; charset=UTF-8"
      }
    ],
    "body" : "{ \"officeId\": 1, \"clientId\": 2, \"savingsId\": 1, ...}"
  }
]

Errors and Error Codes

  • 400 Bad Request - Invalid Parameter or Data Integrity Issue.

  • 401 Authentication Error.

  • 403 Unauthorized Request.

  • 404 Resource Not Found

  • 500 Platform Internal Server Error.

Mifos Community App

The default web application built on top of the MifosX platform for the mifos user community. It is a Single-Page App (SPA) written in web standard technologies like JavaScript, CSS and HTML5. It leverages common popular frameworks/libraries such as AngularJS, Bootstrap and Font Awesome.

 

Community App

Enhancements

  • Retrofitted end points to support Batch API
  • Modified Error Handler
  • Appended Front-end for Bulk JLG Loan Application
  • Modified some Task controllers for more efficient Batch API

Bulk JLG Loan

  • Employs Batch API to add JLG Loans to multiple User accounts, in a single request
  • Common Fields for all the User accounts
  • Specific Fields for individual Users
  • Returns error for individual requests, if any 

Limitations

  • Highly Specific Code
  • Can handle only a limited number of requests (50 - 100)
  • Need to manually code support for further modules

Conclusion

An API Structure like Batch API is a highly desirable feature for platforms that handles a large number of transactions per second. WikiPedia and Facebook are some of the very first platforms for developing a Batch API. 

 

It saves a lot of unused Bandwidth and provides much lesser latency time. And is primarily useful for Syncing, Bulk Operations and offline apps.

Documentation and

Source Code

  • Documentation - https://demo.openmf.org/api-docs/apiLive.htm#batch_api
  • Github Repo(Batch API) -  https://github.com/rishy/mifosx/tree/Batch-API
  • Github Repo(Community App) -  https://github.com/rishy/community-app/tree/MIFOSX-1425

Thank you.

Made with Slides.com