api docs update

This commit is contained in:
John Woodlock
2012-06-01 15:17:14 +10:00
parent 1674b9f600
commit bed2136e0d
4 changed files with 135 additions and 164 deletions
+128 -135
View File
@@ -7,82 +7,6 @@
<title>Mifos X API Documentation</title> <title>Mifos X API Documentation</title>
</head> </head>
<script type="text/javascript">
basicAuthKey = "";
function showMandatoryFields(url, resultDiv) {
if (basicAuthKey == "") setBasicAuthKey(url, resultDiv)
else showMandatoryFieldsAjax(url, resultDiv);
}
function showMandatoryFieldsAjax(url, resultDiv) {
var jqxhr = $.ajax({
url : url,
type : 'POST',
contentType : "application/json; charset=utf-8",
dataType : 'json',
data : "{}",
cache : false,
beforeSend : function(xhr) {
xhr.setRequestHeader("Authorization", "Basic " + basicAuthKey);
},
success : function(data, textStatus, jqXHR) {
$('#' + resultDiv).html("Strangely, There Are No Mandatory Fields");
},
error : function(jqXHR, textStatus, errorThrown) {
if (jqXHR.status === 400) {
errJSON = eval("(" + jqXHR.responseText + ')');
var mandFields = "";
if (resultDiv == 'loans_mandatory') mandFields = "clientId, productId, inArrearsTolerance, submittedOnDate, ";
for ( var i in errJSON.errors) {
if (i == 0) mandFields += errJSON.errors[i].parameterName;
else mandFields += ", " + errJSON.errors[i].parameterName;
}
$('#' + resultDiv).html(mandFields);
return;
}
if (jqXHR.status === 0) {
$('#' + resultDiv).html('No connection.\n Verify Network.');
} else if (jqXHR.status == 404) {
$('#' + resultDiv).html('Requested page not found. [404]');
} else if (jqXHR.status == 500) {
$('#' + resultDiv).html('Internal Server Error [500].');
} else if (errorThrown === 'parsererror') {
$('#' + resultDiv).html('Requested JSON parse failed.');
} else if (errorThrown === 'timeout') {
$('#' + resultDiv).html('Time out error.');
} else if (errorThrown === 'abort') {
$('#' + resultDiv).html('Ajax request aborted.');
} else $('#' + resultDiv).html('Unknown Ajax request problem - jqXHR.status: ' + jqXHR.status);
}
});
}
function setBasicAuthKey(url, resultDiv) {
var jqxhr = $.ajax({
url : "https://localhost:8443/mifosng-provider/api/v1/authentication?username=mifos&password=password",
type : 'POST',
contentType : "application/json; charset=utf-8",
dataType : 'json',
data : "{}",
cache : false,
success : function(data, textStatus, jqXHR) {
basicAuthKey = data.base64EncodedAuthenticationKey;
showMandatoryFieldsAjax(url, resultDiv);
//alert("success");
},
error : function(jqXHR, textStatus, errorThrown) {
alert("error - Might be an SSL certificate problem.\nTry to run a List Offices example (which should force your browser to Proceed Anyway).\nThen Click Back to return to this page and all should be good.");
}
});
}
</script>
<body> <body>
<div id="page-wrapper"> <div id="page-wrapper">
<div id="flybar"> <div id="flybar">
@@ -98,6 +22,7 @@ var jqxhr = $.ajax({
<li><a href="#genopts">Generic Options</a></li> <li><a href="#genopts">Generic Options</a></li>
<li><a href="#creates_and_updates">Creating and Updating</a></li> <li><a href="#creates_and_updates">Creating and Updating</a></li>
<li><a href="#dates_and_numbers">Updating Dates and Numbers</a></li> <li><a href="#dates_and_numbers">Updating Dates and Numbers</a></li>
<li><a href="#field_descriptions">Field Descriptions</a></li>
<li><a href="#authentication_overview">Authentication Overview</a></li> <li><a href="#authentication_overview">Authentication Overview</a></li>
<li><a href="#errors">Errors</a></li> <li><a href="#errors">Errors</a></li>
<li><a href="#fullapi_matrix">Full API Matrix</a></li> <li><a href="#fullapi_matrix">Full API Matrix</a></li>
@@ -336,6 +261,18 @@ JSON examples:
</div> </div>
<a id="field_descriptions" name="field_descriptions" class="old-syle-anchor">&nbsp;</a>
<div class="method-section">
<div class="method-description">
<h3>Field Descriptions</h3>
<p>
Most fields are self-explanatory. Fields that aren't are described under the relevant resource heading e.g. <a href="#authentication">AUTHENTICATION</a>
</p>
</div>
</div>
<a id="authentication_overview" name="authentication_overview" class="old-syle-anchor">&nbsp;</a> <a id="authentication_overview" name="authentication_overview" class="old-syle-anchor">&nbsp;</a>
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
@@ -531,13 +468,21 @@ var jqxhr = $.ajax({
</div> </div>
</div> </div>
<!-- start of clients api docs --> <!-- start of clients api docs -->
<a id="clients" name="clients" class="old-syle-anchor">&nbsp;</a> <a id="clients" name="clients" class="old-syle-anchor">&nbsp;</a>
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
<h3>Clients</h3> <h3>Clients</h3>
<p>Clients are people and businesses that have applied (or may apply) to an MFI for loans.</p> <p>Clients are people and businesses that have applied (or may apply) to an MFI for loans.</p>
<table class=matrixHeading>
<tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Field Descriptions</div></td></tr>
<tr class=alt><td>externalId</td></tr>
<tr><td class=fielddesc>A place to put an external reference for this client e.g. The ID another system uses.</td></tr>
</tr>
</table>
</div> </div>
</div> </div>
@@ -650,14 +595,13 @@ var jqxhr = $.ajax({
<div class="method-description"> <div class="method-description">
<h4>Create a Client</h4> <h4>Create a Client</h4>
<p> <b>Note:</b> You can enter either:<br> <p> <b>Note:</b> You can enter either:<br>
firstname/lastname - for a person<br> firstname/lastname - for a person OR<br>
OR<br>
clientOrBusinessName - for a business or organisation (or person known by one name). clientOrBusinessName - for a business or organisation (or person known by one name).
</p> </p>
<button type="button" onclick="showMandatoryFields('https://localhost:8443/mifosng-provider/api/v1/clients', 'clients_mandatory');">Show Mandatory Fields</button> <table class=matrixHeading>
<br> <tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Mandatory Fields</div></td></tr>
<div id=clients_mandatory></div> <tr class=alt><td>firstname, lastname, joiningDate, officeId</td></tr>
<br> </table>
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/clients</code> <code class="method-declaration">POST https://thedomainname/api/v1/clients</code>
@@ -879,8 +823,14 @@ Request Body:
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
<h3>Loans</h3> <h3>Loans</h3>
<p> <p>overview here
</p> </p>
<table class=matrixHeading>
<tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Field Descriptions</div></td></tr>
<tr class=alt><td>externalId</td></tr>
<tr><td class=fielddesc>A place to put an external reference for this client e.g. The ID another system uses.</td></tr>
</tr>
</table>
</div> </div>
</div> </div>
@@ -1492,11 +1442,6 @@ Request Body:
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
<h4>Create a New Loan/Submit a Loan Application</h4> <h4>Create a New Loan/Submit a Loan Application</h4>
<br>
<button type="button" onclick="showMandatoryFields('https://localhost:8443/mifosng-provider/api/v1/loans', 'loans_mandatory');">Show Mandatory Fields</button>
<br>
<div id=loans_mandatory></div>
<br>
<h5>Arguments</h5> <h5>Arguments</h5>
<dl class="argument-list"> <dl class="argument-list">
<dt>command</dt> <dt>command</dt>
@@ -1506,6 +1451,13 @@ Request Body:
had been submitted) is returned. This gives the ability to try out various loan options and 'preview' the schedule before committing had been submitted) is returned. This gives the ability to try out various loan options and 'preview' the schedule before committing
to it.</dd> to it.</dd>
</dl> </dl>
<br>
<table class=matrixHeading>
<tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Mandatory Fields</div></td></tr>
<tr class=alt><td>clientId, productId, inArrearsTolerance, submittedOnDate, currencyCode, digitsAfterDecimal, principal,
repaymentFrequencyType, repaymentEvery, numberOfRepayments, interestRatePerPeriod, interestRateFrequencyType, amortizationType,
interestType, interestCalculationPeriodType, expectedDisbursementDate</td></tr>
</table>
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/loans</code> <code class="method-declaration">POST https://thedomainname/api/v1/loans</code>
@@ -1544,12 +1496,7 @@ Request Body:
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
<h4>Approve, Undo Approval, Disburse, Undo Disbursal, Reject a Loan or Withdraw a Loan Application</h4> <h4>Approve, Undo Approval, Disburse, Undo Disbursal, Reject a Loan or Withdraw a Loan Application</h4>
<h5>Arguments</h5> <br> <h5>Arguments</h5>
<button type="button" onclick="showMandatoryFields('https://localhost:8443/mifosng-provider/api/v1/loans/37?command=approve', 'loan_state_transition_mandatory');">Show Mandatory Fields</button>
<br>
<div id=loan_state_transition_mandatory></div>
<br>
<dl class="argument-list"> <dl class="argument-list">
<dt>command</dt> <dt>command</dt>
<dd>String<span> Mandatory, case-insensitive</span></dd> <dd>String<span> Mandatory, case-insensitive</span></dd>
@@ -1560,6 +1507,11 @@ Request Body:
<dd>'undoapproval' : Undo Loan Approval</dd> <dd>'undoapproval' : Undo Loan Approval</dd>
<dd>'undodisbursal' : Undo Loan Disbursal</dd> <dd>'undodisbursal' : Undo Loan Disbursal</dd>
</dl> </dl>
<br>
<table class=matrixHeading>
<tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Mandatory Fields</div></td></tr>
<tr class=alt><td>eventDate</td></tr>
</table>
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/loans/{loanId}</code> <code class="method-declaration">POST https://thedomainname/api/v1/loans/{loanId}</code>
@@ -1709,6 +1661,10 @@ Request Body:
<div class="method-description"> <div class="method-description">
<h4>Adjust a Repayment or Waiver</h4> <h4>Adjust a Repayment or Waiver</h4>
<p><b>Note:</b> there is no need to specify command={transactionType} parameter.</p> <p><b>Note:</b> there is no need to specify command={transactionType} parameter.</p>
<table class=matrixHeading>
<tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Mandatory Fields</div></td></tr>
<tr class=alt><td>transactionDate, transactionAmount</td></tr>
</table>
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/loans/{loanId}/transactions/{transactionId}</code> <code class="method-declaration">POST https://thedomainname/api/v1/loans/{loanId}/transactions/{transactionId}</code>
@@ -1739,6 +1695,21 @@ Request Body:
<p>Offices are used to model an MFIs structure. A hierarchial representation of offices is supported. <p>Offices are used to model an MFIs structure. A hierarchial representation of offices is supported.
There will always be at least one office (which represents the MFI or an MFIs head office). There will always be at least one office (which represents the MFI or an MFIs head office).
All subsequent offices added must have a parent office.</p> All subsequent offices added must have a parent office.</p>
<table class=matrixHeading>
<tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Field Descriptions</div></td></tr>
<tr class=alt><td>externalId</td></tr>
<tr><td class=fielddesc>A place to put an external reference for this office e.g. The ID another system uses for it.</td></tr>
</tr>
<tr class=alt><td>hierarchy</td></tr>
<tr><td class=fielddesc>This field is a system generated convenience field. It can't be set.<br>
It uses "dot notation" to define where an office stands in the office hierarchy.<br>
For example, the system default office (id = 1) has a hierarchy value of '.'<br>
An office (id = 12) placed directly underneath this default office has a hierarchy value of '.12.'<br>
And if a further office (id = 78) is placed directly under office (id = 12) its hierarchy value is '.12.78.'<br><br>
The hierarchy value is useful when you need to display offices in 'hierarchy' order (perhaps indented in a drop down list box).
</td></tr>
</tr>
</table>
</div> </div>
</div> </div>
@@ -1852,11 +1823,10 @@ Request Body:
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
<h4>Create an Office</h4> <h4>Create an Office</h4>
<br> <table class=matrixHeading>
<button type="button" onclick="showMandatoryFields('https://localhost:8443/mifosng-provider/api/v1/offices', 'offices_mandatory');">Show Mandatory Fields</button> <tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Mandatory Fields</div></td></tr>
<br> <tr class=alt><td>name, openingDate, parentId</td></tr>
<div id=offices_mandatory></div> </table>
<br>
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/offices</code> <code class="method-declaration">POST https://thedomainname/api/v1/offices</code>
@@ -1867,7 +1837,8 @@ Request Body:
"name": "Example New Branch", "name": "Example New Branch",
"dateFormat": "dd MMMM yyyy", "dateFormat": "dd MMMM yyyy",
"openingDate": "01 July 2007", "openingDate": "01 July 2007",
"parentId": 2 "parentId": 2,
"externalId": "SYS54-88"
} }
</code> </code>
<code class="method-response">{ <code class="method-response">{
@@ -1908,6 +1879,33 @@ Request Body:
<h3>Loan Products</h3> <h3>Loan Products</h3>
<p>A Loan product is a template that is used when creating a loan. Much of the template definition can be overridden during loan creation. <p>A Loan product is a template that is used when creating a loan. Much of the template definition can be overridden during loan creation.
</p> </p>
<table class=matrixHeading>
<tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Field Descriptions</div></td></tr>
<tr class=alt><td>digitsAfterDecimal</td></tr>
<tr><td class=fielddesc>Override the default value for digitsAfterDecimal associated with the currencyCode selected.</td></tr>
</tr>
<tr class=alt><td>principal</td></tr>
<tr><td class=fielddesc>Default loan principal.</td></tr>
<tr class=alt><td>inArrearsTolerance</td></tr>
<tr><td class=fielddesc></td></tr>
<tr class=alt><td>repaymentFrequencyType</td></tr>
<tr><td class=fielddesc></td></tr>
<tr class=alt><td>repaymentEvery</td></tr>
<tr><td class=fielddesc></td></tr>
<tr class=alt><td>numberOfRepayments</td></tr>
<tr><td class=fielddesc></td></tr>
<tr class=alt><td>interestRatePerPeriod</td></tr>
<tr><td class=fielddesc></td></tr>
<tr class=alt><td>interestRateFrequencyType</td></tr>
<tr><td class=fielddesc></td></tr>
<tr class=alt><td>amortizationType</td></tr>
<tr><td class=fielddesc></td></tr>
<tr class=alt><td>interestType</td></tr>
<tr><td class=fielddesc></td></tr>
<tr class=alt><td>interestCalculationPeriodType</td></tr>
<tr><td class=fielddesc></td></tr>
</tr>
</table>
</div> </div>
</div> </div>
@@ -2282,16 +2280,16 @@ Request Body:
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
<h4>Create a Loan Product</h4> <h4>Create a Loan Product</h4>
<br> <table class=matrixHeading>
<button type="button" onclick="showMandatoryFields('https://localhost:8443/mifosng-provider/api/v1/loanproducts', 'loanproducts_mandatory');">Show Mandatory Fields</button> <tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Mandatory Fields</div></td></tr>
<br> <tr class=alt><td>name, currencyCode, digitsAfterDecimal, principal, inArrearsTolerance, repaymentFrequencyType, repaymentEvery,
<div id=loanproducts_mandatory></div> numberOfRepayments, interestRatePerPeriod, interestRateFrequencyType, amortizationType,
<br> interestType, interestCalculationPeriodType</td></tr>
<p>Probably need to describe some of the fields here.</p> </table>
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/loanproducts</code> <code class="method-declaration">POST https://thedomainname/api/v1/loanproducts</code>
<code class="method-request">https://localhost:8443/mifosng-provider/api/v1/loanproducts <code class="method-request">POST https://localhost:8443/mifosng-provider/api/v1/loanproducts
Content-Type: application/json Content-Type: application/json
Request Body: Request Body:
{ {
@@ -2302,14 +2300,14 @@ Request Body:
"locale": "en_GB", "locale": "en_GB",
"principal": "100,000.00", "principal": "100,000.00",
"inArrearsTolerance": "1,000.00", "inArrearsTolerance": "1,000.00",
"numberOfRepayments": "12",
"repaymentEvery": "1",
"repaymentFrequencyType": 2, "repaymentFrequencyType": 2,
"repaymentEvery": "1",
"numberOfRepayments": "12",
"interestRatePerPeriod": "1.75", "interestRatePerPeriod": "1.75",
"interestRateFrequencyType": 2, "interestRateFrequencyType": 2,
"amortizationType": 1, "amortizationType": 1,
"interestCalculationPeriodType": 1, "interestType": 0,
"interestType": 0 "interestCalculationPeriodType": 1
} }
</code> </code>
<code class="method-response">{ <code class="method-response">{
@@ -2326,7 +2324,7 @@ Request Body:
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/loanproducts/{loanId}</code> <code class="method-declaration">POST https://thedomainname/api/v1/loanproducts/{loanId}</code>
<code class="method-request">https://localhost:8443/mifosng-provider/api/v1/loanproducts/1 <code class="method-request">POST https://localhost:8443/mifosng-provider/api/v1/loanproducts/1
Content-Type: application/json Content-Type: application/json
Request Body: Request Body:
{ {
@@ -2348,7 +2346,7 @@ Request Body:
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
<h3>Configuration</h3> <h3>Configuration</h3>
<p>Application related configuration like being able to select the currencies permitted for use within the MFI.</p> <p>Application related configuration. For example, selecting the currencies permitted for use within the MFI.</p>
</div> </div>
</div> </div>
@@ -2850,7 +2848,14 @@ Request Body:
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
<h3>Authentication</h3> <h3>Authentication</h3>
<p>An API capability to allowed client applications verify authentication details.</p> <p>An API capability that allows client applications to verify authentication details.</p>
<table class=matrixHeading>
<tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Field Descriptions</div></td></tr>
<tr class=alt><td>base64EncodedAuthenticationKey</td></tr>
<tr><td class=fielddesc>HTTP Basic Auth key.
See <a href="#authentication_overview">Authentication Overview</a> for an example of its use.</td></tr>
</tr>
</table>
</div> </div>
</div> </div>
@@ -2859,14 +2864,6 @@ Request Body:
<div class="method-description"> <div class="method-description">
<h4>Verify authentication</h4> <h4>Verify authentication</h4>
<p>Authenticates the credentials provided and returns the set of permissions allowed.</p> <p>Authenticates the credentials provided and returns the set of permissions allowed.</p>
<table class=matrixHeading>
<tr class="matrixHeadingBG"><td><div class="matrixHeadingVerbs">Field Descriptions</div></td></tr>
<tr class=alt><td>base64EncodedAuthenticationKey</td></tr>
<tr><td class=fielddesc>HTTP Basic Auth key.
See <a href="#authentication_overview">Authentication Overview</a> for an example of its use.</td></tr>
</tr>
</table>
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/authentication?username={username}&password={password}</code> <code class="method-declaration">POST https://thedomainname/api/v1/authentication?username={username}&password={password}</code>
@@ -3061,12 +3058,10 @@ No Request Body
<p><b>Note:</b> Password information is not required (or processed). Password details are auto-generated and then sent to the email account given <p><b>Note:</b> Password information is not required (or processed). Password details are auto-generated and then sent to the email account given
(which is why it can take a few seconds to complete). (which is why it can take a few seconds to complete).
</p> </p>
<br> <table class=matrixHeading>
<button type="button" onclick="showMandatoryFields('https://localhost:8443/mifosng-provider/api/v1/users', 'users_mandatory');">Show Mandatory Fields</button> <tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Mandatory Fields</div></td></tr>
<br> <tr class=alt><td>username, firstname, lastname, email, officeId, roles</td></tr>
<div id=users_mandatory></div> </table>
<br>
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/users</code> <code class="method-declaration">POST https://thedomainname/api/v1/users</code>
@@ -3272,12 +3267,10 @@ No Request Body
<div class="method-section"> <div class="method-section">
<div class="method-description"> <div class="method-description">
<h4>Create a New Role</h4> <h4>Create a New Role</h4>
<br> <table class=matrixHeading>
<button type="button" onclick="showMandatoryFields('https://localhost:8443/mifosng-provider/api/v1/roles', 'roles_mandatory');">Show Mandatory Fields</button> <tr class="matrixHeadingBG"><td><div class="mifosXHeading2">Mandatory Fields</div></td></tr>
<br> <tr class=alt><td>name, description, permissions</td></tr>
<div id=roles_mandatory></div> </table>
<br>
</div> </div>
<div class="method-example"> <div class="method-example">
<code class="method-declaration">POST https://thedomainname/api/v1/roles</code> <code class="method-declaration">POST https://thedomainname/api/v1/roles</code>
+7 -2
View File
@@ -43,9 +43,14 @@
color: rgb(240, 240, 255); color: rgb(240, 240, 255);
} }
.mifosXHeading2 {
color: white;
font-weight: bold;
//font-size: 125%
}
.fielddesc { .fielddesc {
padding-bottom:20px; padding-bottom:10px;
padding-left:40px; padding-left:20px;
} }
-23
View File
@@ -1,23 +0,0 @@
<div class="method-section">
<div class="method-description">
<h5>Attributes</h5>
<dl class="argument-list">
<dt>
id
</dt>
<dd>
string <span>jpw ipsum as an example of showing the (at least important) columns</span>
</dd>
<dt>
amount
</dt>
<dd>blah <span></span>
</dd>
<dd>blah</dd>
<dt>
card
</dt>
</dl>
</div>
</div>
-4
View File
File diff suppressed because one or more lines are too long