The Mifos X API is organized around REST. - Our API is designed to have predictable, resource-oriented - URLs, to use HTTP response codes to indicate API errors, and - to use built-in HTTP features, like HTTP authentication and +
+
+ The API is designed to have:
+ - predictable, resource-oriented URLs
+ - to use HTTP response codes to indicate API errors
+ - to use built-in HTTP features, like HTTP authentication and
HTTP verbs, which can be understood by off-the-shelf HTTP
- clients. JSON will be
- returned in all responses from the API, including errors.
+ clients.
+
JSON is returned in all responses from the API, including errors.
Much of the API presentation and design ideas are owed to the excellent Apigee "Web API Design" eBook/PDF and the very good Stripe API reference. @@ -228,7 +229,11 @@ var jqxhr = $.ajax({
GET (read) examples can be run directly from this documentation. If you want to check out the POST, PUT and DELETE (update) examples a good approach is to +
GET (read) examples can be run directly from this documentation. It is just a matter of clicking a link. + Most browsers display the output on the same page (or another tab if you right click and select that option). + Internet Explorer will probably treat the output as if you wanted to download a file. + In that case just elect to open the output in a text editor.
+If you want to check out the POST, PUT and DELETE (update) examples a good approach is to take a moment to install a REST plugin for your browser e.g. RESTClient for FireFox
The REST plugins will allow you toAlso, many "Retrieve a" type resource (Retrieve a Client for example) allow the parameter option "template=true". +
Also, many "Retrieve a" type resources (Retrieve a Client for example) allow the parameter option "template=true". This appends any "Allowed Value Lists" which can be useful when building update functionality.
Parameter "pretty=true" can be used to display JSON from GET requests in an easily readable format. This parameter is used in this documentation so that GET requests are immediately viewable.
-If you want easily readable JSON output for POSTs, PUTs and DELETEs it will available in the REST plugin you use e.g. RESTClient for FireFox
+Parameter "pretty=true" can be used to display JSON from GET requests in an easy-to-read format. + This parameter is used in this documentation.
+Easy-to-read JSON output for POSTs, PUTs and DELETEs will available in the REST plugin you use e.g. RESTClient for FireFox
- When you want to 'Create a...' you have to at least supply the mandatory fields. - You can see which fields are mandatory by clicking the 'Show Mandatory Fields' button under the relevant 'Create a ...' heading. + When you want to 'Create a ...' you have to at least supply the mandatory fields. + The mandatory fields are listed in this documentation under the relevant 'Create a ...' heading.
- When you want to 'Update a...' you can update individual fields or a combination of fields (subject to data integrity rules). + When you want to 'Update a ...' you can update individual fields or a combination of fields (subject to data integrity rules).
- JPW: Keith, this needs to change to whatever is right after authentication has been added. Don't know if you will go with keys or passwords (I assume passwords)... but can you fix it so we have one user or one user per role that doesn't need a password or always has a password of 'password' so we can let ppl do stuff from the browser and/or REST plugins? We can talk about this. -
-- STRIPE content: You authenticate to the Mifos X API by providing one of - your API keys in the request. You can manage your API - keys from your - account. - You can have multiple API keys - active at one time. Your API keys carry many - privileges, so be sure to keep them secret! + Authentication to the API occurs via HTTP Basic Auth.
- Authentication to the API occurs via - - HTTP Basic Auth. Provide your API key as the basic - auth username. You do not need to provide a password. -
- -- All API requests must be made - over HTTPS. - Calls made over plain HTTP will fail. You must - authenticate for all requests. + All API requests must be made over HTTPS. + Calls made over plain HTTP will fail. You must authenticate for all requests.
curl https://api.stripe.com/api/v1/charges \
- -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE:
+
+// A Javascript/Jquery example of how to login to Mifos X and use its api.
+
+// Typically, the javascript application would
+// 1) Display a login page to retrieve the username and password.
+// 2) Send the username and password to a function
+// such as setBasicAuthKey below which sets the HTTP Basic Auth key.
+// 3) The HTTP Basic Auth key is used in all subsequent requests
+// (see the function executeAjaxRequest below).
+
+function setBasicAuthKey(username, password) {
+var jqxhr = $.ajax({
+ url : "https://localhost:8443/mifosng-provider/api/v1/authentication?username=" + username + "&password=" + password,
+ type : 'POST',
+ contentType : "application/json; charset=utf-8",
+ dataType : 'json',
+ data : "{}",
+ cache : false,
+ success : function(data, textStatus, jqXHR) {
+ basicAuthKey = data.base64EncodedAuthenticationKey;
+ },
+ error : function(jqXHR, textStatus, errorThrown) {
+ //error processing
+ }
+ });
+}
+
+function executeAjaxRequest(url, verbType, jsonData, basicAuthKey, successFunction, errorFunction) {
+var jqxhr = $.ajax({
+ url : url,
+ type : verbType, //POST, GET, PUT or DELETE
+ contentType : "application/json; charset=utf-8",
+ dataType : 'json',
+ data : jsonData,
+ cache : false,
+ beforeSend : function(xhr) {
+ xhr.setRequestHeader("Authorization", "Basic " + basicAuthKey);
+ },
+ success : successFunction,
+ error : errorFunction
+ });
+}
-
- JPW: We'll update this after...
- curl uses the -u flag to pass basic auth
- credentials (adding a colon after your API key will prevent
- it from asking you for a password).
-
- A sample test API key has been provided in all
- the examples on the page, so you can test out any example right away.
-
-
POST https://thedomainname/api/v1/loans/{loanId}/transactions/{transactionId}
POST https://localhost:8443/mifosng-provider/api/v1/loans/16/transactions/32
Content-Type: application/json
-Request Body:{
+Request Body:
+{
"locale": "en_GB",
"dateFormat": "dd MMMM yyyy",
"transactionDate": "25 May 2012",
@@ -2852,6 +2859,14 @@ Request Body:
Verify authentication
Authenticates the credentials provided and returns the set of permissions allowed.
+
+
+ Field Descriptions base64EncodedAuthenticationKey HTTP Basic Auth key.
+ See Authentication Overview for an example of its use.
POST https://thedomainname/api/v1/authentication?username={username}&password={password}
diff --git a/APIFolder/apidocs.css b/APIFolder/apidocs.css
index 9a31362ea..4ba858044 100644
--- a/APIFolder/apidocs.css
+++ b/APIFolder/apidocs.css
@@ -10,7 +10,7 @@
.matrixHeading {
font-family: Helvetica, Arial, sans-serif;
border-collapse:collapse;
- border:3px solid #6eb4db;
+ border 3px solid #6eb4db;
width:100%;
}
@@ -43,6 +43,12 @@
color: rgb(240, 240, 255);
}
+.fielddesc {
+ padding-bottom:20px;
+ padding-left:40px;
+}
+
+
.normalli {list-style:disc outside none;}
diff --git a/APIFolder/docUpdateComments.txt b/APIFolder/docUpdateComments.txt
index def19b76e..5c3b551bb 100644
--- a/APIFolder/docUpdateComments.txt
+++ b/APIFolder/docUpdateComments.txt
@@ -1,71 +1,72 @@
-Lost permissions again... restore fixed it up... must be some prob with permissions/roles maintenance
-also, maybe I should be using a user that has everything but role admin.
-recreate() problem ME DO - couldn't recreate by update user roles... maybe was to do with office 1 have a parentId?
-
+POSSIBLE CHANGES TO APP OR DOCUMENTATION
list clients notes - noteType needs a 'text' DOING
createdOn & updatedOn values... do they need reformatting? DOING
-updating client note - ignores clientId anyhow! so is it really a notes resource? DOING
-loan template
-Formatted field still there DOING
+updating client note - produces valid json message although if the clientId is wrong the msg is "Note with identifier 25 does not exist" rather than something like "Note with client identifier 25 does not exist"
+
+
+loan template - repaymentSchedule is null - I can't see it set in the app
+
loan retrieve DOING
-break up data into categories.. e.g.
-Basic - lifeCycleStatusText thru
-Convenience - open thru waitingForDisbursal then maxSubmittedOnOffsetFromToday, maxApprovedOnOffsetFromToday , maxDisbursedOnOffsetFromToday, actualLoanTermInDays, actualLoanTermInMonths, loanTermInDays, loanTermInMonths
-Permission - undoDisbursalAllowed, waiveAllowed, makeRepaymentAllowed, rejectAllowed, withdrawnByApplicantAllowed, undoApprovalAllowed, disbursalAllowed, anyActionOnLoanAllowed
-
-flatten loadData
-repaymentSchedule
-summary
-loanRepayments
-
----------------------------------------------
-LOAN TRANSITIONS approve etc.
-if "eventLocalDate" parameter added with string date then instead of parameter not support msg do get jackson conversion exception.
-
-approve loan (already closed) with approval date before submitted date
-The server encountered an internal error () that prevented it from fulfilling this request.exception
org.mifosng.platform.loan.domain.InvalidLoanTimelineDate: The date of when loan is approved cannot be before its submittal date.
-
-approve loan (already closed) with approval date after submitted date
-Column 'loan_status_id' cannot be null; SQL [n/a]; constraint [null]; nested exception is org.hibernate.exception.ConstraintViolationException: Column 'loan_status_id' cannot be null
-
-if I do an approve when already approved also get
-Column 'loan_status_id' cannot be null; SQL [n/a]; constraint [null]; nested exception is org.hibernate.exception.ConstraintViolationException: Column 'loan_status_id' cannot be null
+ break up data into categories.. e.g.
+ Basic - lifeCycleStatusText thru
+ Convenience - open thru waitingForDisbursal then maxSubmittedOnOffsetFromToday, maxApprovedOnOffsetFromToday , maxDisbursedOnOffsetFromToday, actualLoanTermInDays, actualLoanTermInMonths, loanTermInDays, loanTermInMonths
+ Permission - undoDisbursalAllowed, waiveAllowed, makeRepaymentAllowed, rejectAllowed, withdrawnByApplicantAllowed, undoApprovalAllowed, disbursalAllowed, anyActionOnLoanAllowed
+ flatten loadData
+ repaymentSchedule
+ summary
+ loanRepayments
+Loan Transitions ... approve etc
+ if "eventLocalDate" parameter added with string date then instead of parameter not support msg do get jackson conversion exception.
+ approve loan (already closed) with approval date before submitted date
+ The server encountered an internal error () that prevented it from fulfilling this request.exception
org.mifosng.platform.loan.domain.InvalidLoanTimelineDate: The date of when loan is approved cannot be before its submittal date.
+
+ approve loan (already closed) with approval date after submitted date
+ Column 'loan_status_id' cannot be null; SQL [n/a]; constraint [null]; nested exception is org.hibernate.exception.ConstraintViolationException: Column 'loan_status_id' cannot be null
+
+ if I do an approve when already approved also get
+ Column 'loan_status_id' cannot be null; SQL [n/a]; constraint [null]; nested exception is org.hibernate.exception.ConstraintViolationException: Column 'loan_status_id' cannot be null
+
+ sometimes clientId returned... always loanId OK?
-sometimes clientId returned... always loanId OK?
-
-LOAN TRANSACTIONS (repay and waive - and maybe reversal - but not disbursement) general talk needed as retrieve could work for any txn?
-transaction type... UNKNOWN(0), DISBURSEMENT(1), REPAYMENT(2), REVERSAL(3), WAIVED(4);
-Create - (command has string and proper value fields... so assume its like eventDate above)
-If you undo disbursal does it undo the loantransaction? - didnt test
-Template - does waiver amount default to 'rest of loan' cos it looked like it missed out on other waivers. didn't test
+Loan Transactions (repay and waive - and maybe reversal - but not disbursement) general talk needed as retrieve could work for any txn?
+ transaction type... UNKNOWN(0), DISBURSEMENT(1), REPAYMENT(2), REVERSAL(3), WAIVED(4);
+ Create - (command has string and proper value fields... so assume its like eventDate above)
+ If you undo disbursal does it undo the loantransaction? - didnt test
+ Template - does waiver amount default to 'rest of loan' cos it looked like it missed out on other waivers. didn't test
repayment amount matches current installment outstanding amount w/o taking waivers into account.
-check descriptions - couldn't test because of invalid locale
+ check descriptions - couldn't test because of invalid locale
+ retrieve: display transaction type value?
+ "principal" : null, "interest" : null, total, "totalWaived" : null, "overpaid" : null, and the offset - are nulls ever put in?
+ adjust:
+ when adjusting a disbursal - The server encountered an internal error () that prevented it from fulfilling this request.exception
java.lang.IllegalArgumentException: Only repayment and waiver transactions can be adjusted.
+ on create and adjust, app returns clientId can it be transaction id or loanId?
-retrieve: display transaction type value?
-"principal" : null, "interest" : null, total, "totalWaived" : null, "overpaid" : null, and the offset - are nulls ever put in?
-adjust:
-when adjusting a disbursal - The server encountered an internal error () that prevented it from fulfilling this request.exception
java.lang.IllegalArgumentException: Only repayment and waiver transactions can be adjusted.
+BUT NOT FOR NOWS
+should be able to get clients by branch as well
+also get loans of different status's by branch etc
+list of loan transactions not available (except in summary - presume repayments section has repayments and waivers and adjusts)
- on create and adjust returns clientId can it be transaction id or loanId?
-list of loan transactions not available (except in summary presume repayments has repayments and waivers and adjusts)
----------------------------------------------------------
-should be able to get clients by branch as well (but not for now)
-also get loans of different status's by branch etc (but not for now)
+
+
+DOCUMENTATION REMAINING
+
+Just Errors section to do in the Overview section
Loans - what does Keith think about a description
Identify Fields that need explaining
+=========================
Clients
displayName, externalId, maxJoinedOnOffsetFromToday