Developer deep dive into Http API

Developer deep dive into Http API

Introduction

One of the key enablers of the faster, lighter, cheaper approach behind this MIS over the existing version of mifos is the API.

Heres an overview of what its based on:

1. The API is resource-oriented. Whilst not what some would view as full REST, it is a pragmatic approach.
2. Its developer-oriented. The purpose of the API is to make the developer that uses it successful and productive.
3. As such the API should be predictable and simple to learn and use

We can achieve this through:

1. Resource URLs will be simple and intuitive - try to keep to at most two levels of resource nesting
2. Use HTTP verbs for operating on resources - @GET, @POST, @PUT, @DELETE
3. Use plural nouns and concrete names - e.g. loanproducts over loanproduct or higher abstraction of products.
4. Simplify associations - e.g. /resource/identifier/resource
5. Move complexity into query parameters - e.g. /loans?active=true
6. Use small set of standard HTTP error code responses
7. JSON will be returned in all responses from the API, including errors

Predictable, Simple and Intuitive pattern

1. /loanproducts [@GET list all / @POST create new]
2. /loanproducts/21 [@GET list loanproduct 21 / @PUT update loanproduct 21]
3. /offices [@GET list all / @POST create new]
4. /offices /21 [@GET list office 21 / @PUT update office 21]

Jersey setup

In mifosx we use Jersey and its support for integration with spring. see https://wikis.oracle.com/display/Jersey/Main

In the mifosngprovider/src/main/webapp/WEB-INF/web.xml you will see configuration for a servlet named jersey-serlvet that is mapped to /api/*. This allows for all requests that begin with /api to be routed through Jersey e.g. https://localhost:8085/mifosng-provider/api/v1/loanproducts

The support for com.sun.jersey.spi.spring.container.servlet.SpringServlet class used comes from Jerseys spring-integration project. See mifosngprovider/build.gradle for the dependencies.

URL Prefix

All urls start with /api/{version} e.g /api/v1 which might be availabe at https://localhost:8085/mifosng-provider/api/v1/...

Root resources

Root resources are those at the first level of hte URL e.g. /loanproducts

In mifosx, we create a Java class to represent the resource and annotate it with Jersey @Path annotation to tell jersey to route requests that match the url path. e.g @Path("/v1/loanproducts")

see mifosngprovider/src/main/java/org/mifosng/platform/api/LoanProductApiResource.java as an example.

Note: At present putting resources under package org.mifosng.platform.api of the mifosngprovider project.

List of Resources

1. /loanproducts
2. /offices