MambuPy for REST V2

MambuPy v2 is a design and development effort to make MambuPy compatible with Mambu’s REST API v2.

Besides the compatibility with the more recent version of Mambu’s API, the main design objective of MambuPy v2 is to have a good design and best practices, with a KISS and DRY philosophy.

MambuPy v2 DOES NOT pretends to be backwards compatible with v1, please be aware of the implications for your code.

If you are looking for documentation of v1 for MambuPy, look here: MambuPy for REST.

The idea behind MambuPy v2 is to implement functionality to interact with Mambu using Mambu’s REST API endpoints. Even if one of its objectives is to implement each and every endpoint offered by the REST API, the implementation should not be thinked about as just making “Python endpoints” for Mambu. The idea is to offer Mambu’s functionality, through the REST API, with python technology.

MambuPy v2 also pretends to achieve at some stage a unification of interfaces, so ORM and REST MambuPy modules would be managed in the same fashion. In fact we pretend to use the very same objects for both interfaces, specifying a specific type of connection to some Mambu data source (may it be the API REST or a connection to a database backup as you pick).

Current Status

MambuPy v2 is in a beta-testing stage. There are some users developing based on it.

Beta Test means that you now have almost every Mambu Entity you had on MambuPy v1 rest module (except for savings and transaction channels).

Also, Activities is currently not supported by Mambu REST API v2, so we are unable to implement any functionality around it.

What follows, is a description of how MambuPy v2 is designed and some implementation details are given, with the purpose of explaining how it currently works.

Class Diagrams

Every entity of Mambu inherits from MambuPy.api.entities.MambuEntity or variations of it, which implements several interfaces to connect with Mambu.

The main (and common to all entities) interface, gives the get and get_all endpoints to any Entity, since at least every entity implemented in MambuPy supports both functionality.

There are also other interfaces that gives extra functionalities to entities inheriting from them. Currently supported:

There are also other interfaces for some extra functionality, not directly related with endpoints at Mambu REST API. Look at MambuPy.api.entities for further information.

The following diagram illustrates the currently implemented entities:

_images/mambupyv2_entities.png

MambuStruct

If you recall how MambuPy v1 works, MambuPy.rest.mambustruct.MambuStruct is a fundamental class for it.

v2 also has a MambuPy.api.mambustruct.MambuStruct, but what v1 did in a single class, v2 does in several ones, organized in a more ordered fashion.

The real father of all MambuPy v2 classes is MambuPy.api.classes.MambuMapObj, which implements dictionary and object-like behaviour to access the fundamental data structure of MambuPy v2 entities: MambuPy.api.mambustruct.MambuStruct._attrs

Then, MambuStruct inherits from this, implementing the conversion, serialization, extraction and update behavior over the _attrs dictionary. This is similar to what we’ve described at Single entities from Mambu, but with further functionality.

_images/mambupyv2_entities_ancestors.png

At last, comes the real action. MambuPy.api.entities.MambuEntity inherits from MambuStruct, implementing real Mambu operations for a given entity.

Mambu Entities raison d’être is to implement those entities with which you may interact using Mambu web: clients, groups, loan accounts, branches, users, etc.

However, MambuEntity is not the only one inheriting from MambuStruct…

ValueObjects

When you make a GET request to some Mambu endpoint, let’s say to retrieve a Centre, you get something like this:

{
  "_Example_Custom_Fields": {
    "exampleCheckboxField": "TRUE",
    "exampleFreeTextField": "A free text field up to 255 characters in length",
    "exampleNumberField": "46290",
    "exampleSelectField": "Option 1"
  },
  "_centres_custom_field_set": {
    "centre_cf_1": "string",
    "cntr_cf_2": "TRUE",
    "cntr_cf_usr_lnk": "string"
  },
  "_cntr_cf_grp": [
    {
      "cntr_cf_Grp_1": "string",
      "cntr_cf_grp_2": "option 1",
      "cntr_cf_slct_2": "dep 1 a"
    },
    {
      "cntr_cf_Grp_1": "other string",
      "cntr_cf_grp_2": "option 2",
      "cntr_cf_slct_2": "dep 2 b"
    }
  ],
  "addresses": [
    {
      "city": "string",
      "country": "string",
      "encodedKey": "string",
      "indexInList": 0,
      "latitude": 0,
      "line1": "string",
      "line2": "string",
      "longitude": 0,
      "parentKey": "string",
      "postcode": "string",
      "region": "string"
    }
  ],
  "assignedBranchKey": "string",
  "creationDate": "2016-09-06T13:37:50+03:00",
  "encodedKey": "string",
  "id": "string",
  "lastModifiedDate": "2016-09-06T13:37:50+03:00",
  "meetingDay": "string",
  "name": "string",
  "notes": "string",
  "state": "ACTIVE"
}

As you may notice, the Centre object has attribute of many different types (translated to python’s native data types with a call of MambuPy.api.mambustruct.MambuStruct._convertDict2Attrs()).

But what about such types conformed by structures of native data types? Let’s talk about addresses:

"addresses": [
  {
    "city": "string",
    "country": "string",
    "encodedKey": "string",
    "indexInList": 0,
    "latitude": 0,
    "line1": "string",
    "line2": "string",
    "longitude": 0,
    "parentKey": "string",
    "postcode": "string",
    "region": "string"
  }
]

As you may note, it’s kind of a list of element. And each element includes several fields, always the same fields, which conform an Address.

Also, there are no endpoints in Mambu’s REST API to interact with addresses. They’re just part of some entity that may have addresses on it (Centres in this example, but also Branches, Clients, and Groups).

Wouldn’t it be nice to manage this structures using MambuPy’s facilities?

This is where MambuPy v2 Value Objets come in to play. Inheriting every functionality MambuStruct can offer, specially what its father MambuMapObj has to offer, a MambuPy ValueObject is just what its name implies: an object that acquires certain value.