api docs update

APIFolder/api.htm

@@ -71,9 +71,6 @@ var jqxhr = $.ajax({
         dataType : 'json',
         data : "{}",
         cache : false,
-        //beforeSend : function(xhr) {
-        //        xhr.setRequestHeader("Authorization", "Basic " + basicAuthKey);
-        //},
         success : function(data, textStatus, jqXHR) {     
             basicAuthKey = data.base64EncodedAuthenticationKey;
             showMandatoryFieldsAjax(url, resultDiv);
@@ -210,12 +207,16 @@ var jqxhr = $.ajax({
                 <p>
                 The Mifos X API is organized around
                 <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST</a>.
-                Our API is designed to have predictable, resource-oriented
+                </p>
-                URLs, to use HTTP response codes to indicate API errors, and
+                <p>
-                to use built-in HTTP features, like HTTP authentication and
+                The API is designed to have: <br>
+                - predictable, resource-oriented URLs<br>
+                - to use HTTP response codes to indicate API errors<br>
+                - to use built-in HTTP features, like HTTP authentication and
                 HTTP verbs, which can be understood by off-the-shelf HTTP
-                clients. <a href="http://www.json.org/">JSON</a> will be
+                clients.
-                returned in all responses from the API, including errors.
+                </p>
+                <p><a href="http://www.json.org/">JSON</a> is returned in all responses from the API, including errors.
                 </p>
                 <p>
                 Much of the API presentation and design ideas are owed to the excellent <a href="http://info.apigee.com/Portals/62317/docs/web%20api.pdf">Apigee "Web API Design" eBook/PDF</a> and the very good <a href="https://stripe.com/docs/api">Stripe API reference</a>. 
@@ -228,7 +229,11 @@ var jqxhr = $.ajax({
         <div class="method-section">
             <div class="method-description">
                 <h3>Try The API From Your Browser</h3>
-                <p>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
+                <p>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.</p>
+                <p>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</p>
                 The REST plugins will allow you to
                 <ul>
@@ -236,7 +241,7 @@ var jqxhr = $.ajax({
                     <li class=normalli>Enter the resource name (e.g. https://localhost:8443/mifosng-provider/api/v1/offices)</li>
                     <li class=normalli>Add a header to indicate you are sending JSON data as part of the request body (e.g. Content-Type: application/json)</li>
                     <li class=normalli>Paste the example JSON into a Request Body</li>
-                    <li class=normalli>Send the Request (and recieve a Response)</li>
+                    <li class=normalli>Send the Request (and receive a Response)</li>
                 </ul>
              </div>
     
@@ -254,7 +259,7 @@ var jqxhr = $.ajax({
                     <li class=normalli>Allowed Value Lists</li>    
                     </ul>
                 </p>
-                <p>Also, many "Retrieve a" type resource (<a href="#clients_retrieve">Retrieve a Client</a> for example) allow the parameter option "template=true".
+                <p>Also, many "Retrieve a" type resources (<a href="#clients_retrieve">Retrieve a Client</a> for example) allow the parameter option "template=true".
                 This appends any "Allowed Value Lists" which can be useful when building update functionality.</p>
                 
                 <h4>Restrict Returned Fields</h4>
@@ -265,8 +270,9 @@ var jqxhr = $.ajax({
                 </a>
                 <p></p>
                 <h4>Pretty JSON Formatting</h4>
-                <p>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.</p>
+                <p>Parameter "pretty=true" can be used to display JSON from GET requests in an easy-to-read format.
-                <p>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</p>
+                This parameter is used in this documentation.</p>
+                <p>Easy-to-read JSON output for POSTs, PUTs and DELETEs will available in the REST plugin you use e.g. RESTClient for FireFox</p>
             </div>
     
         </div>
@@ -276,12 +282,12 @@ var jqxhr = $.ajax({
             <div class="method-description">
                 <h3>Creating and Updating</h3>
                 <p>
-                When you want to 'Create a...' you have to at least supply the mandatory fields.
+                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.
+                The mandatory fields are listed in this documentation under the relevant 'Create a ...' heading.
                 </p>
                 
                 <p>
-                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).
                 </p>
             </div>
     
@@ -335,46 +341,58 @@ JSON examples:
             <div class="method-description">
                 <h3>Authentication Overview</h3>              
                 <p>
-                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.
+                Authentication to the API occurs via <a href="http://en.wikipedia.org/wiki/Basic_access_authentication">HTTP Basic Auth</a>.  
-                </p>
-                <p>
-                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
-                <a href="https://manage.stripe.com/#account">account</a>.
-                You can have multiple API keys
-                active at one time.  Your API keys carry many
-                privileges, so be sure to keep them secret!
                 </p>
                 
                 <p>
-                Authentication to the API occurs via
+                All API requests must be made over <a href="http://en.wikipedia.org/wiki/HTTP_Secure">HTTPS</a>.
-                <a href="http://en.wikipedia.org/wiki/Basic_access_authentication">
+                Calls made over plain HTTP will fail.  You must authenticate for all requests.
-                HTTP Basic Auth</a>.  Provide your API key as the basic
-                auth username.  You do not need to provide a password.
-                </p>
-                
-                <p>
-                All API requests must be made
-                over <a href="http://en.wikipedia.org/wiki/HTTP_Secure">HTTPS</a>.
-                Calls made over plain HTTP will fail.  You must
-                authenticate for all requests.
                 </p>
             </div>
             <div class="method-example">
-                <code class="method-request"><span class="prompt curl"></span>curl https://api.stripe.com/api/v1/charges \
+                <code>
-        -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
+    });
+}
                 </code>
-                <p>
-                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.
-                
-                </p>
             </div>
         </div>
     
@@ -897,39 +915,6 @@ Request Body:
   "clientName" : "Patrick O'Meara",
   "productId" : 1,
   "productName" : "Agricultural Loan",
-  "allowedProducts" : [ {
-    "id" : 1,
-    "name" : "Agricultural Loan"
-  }, {
-    "id" : 2,
-    "name" : "Brunei Loan"
-  }, {
-    "id" : 3,
-    "name" : "IL Loan"
-  }, {
-    "id" : 4,
-    "name" : "IBL Mabeshte"
-  }, {
-    "id" : 5,
-    "name" : "Salary Loan"
-  }, {
-    "id" : 6,
-    "name" : "daily-declining-balance"
-  }, {
-    "id" : 7,
-    "name" : "really fantastic loan"
-  } ],
-  "dateFormat" : null,
-  "submittedOnDateFormatted" : null,
-  "submittedOnDate" : null,
-  "submittedOnNote" : "",
-  "expectedDisbursementDateFormatted" : null,
-  "expectedDisbursementDate" : [ 2012, 5, 31 ],
-  "repaymentsStartingFromDateFormatted" : null,
-  "repaymentsStartingFromDate" : null,
-  "interestCalculatedFromDateFormatted" : null,
-  "interestCalculatedFromDate" : null,
-  "repaymentSchedule" : null,
   "selectedProduct" : {
     "id" : 1,
     "name" : "Agricultural Loan",
@@ -1079,7 +1064,28 @@ Request Body:
       "code" : "interestRateFrequency.periodFrequencyType.years",
       "value" : "Per year"
     } ]
-  }
+  },
+  "expectedDisbursementDate" : [ 2012, 6, 1 ],
+  "repaymentSchedule" : null,
+  "allowedProducts" : [ {
+    "id" : 1,
+    "name" : "Agricultural Loan"
+  }, {
+    "id" : 2,
+    "name" : "Brunei Loan"
+  }, {
+    "id" : 3,
+    "name" : "IL Loan"
+  }, {
+    "id" : 4,
+    "name" : "IBL Mabeshte"
+  }, {
+    "id" : 5,
+    "name" : "Salary Loan"
+  }, {
+    "id" : 6,
+    "name" : "daily-declining-balance"
+  } ]
 }
 </code>
     </div>
@@ -1708,7 +1714,8 @@ Request Body:
                 <code class="method-declaration">POST https://thedomainname/api/v1/loans/{loanId}/transactions/{transactionId}</code>
                 <code class="method-request">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:
 	    <div class="method-description">
 	        <h4>Verify authentication</h4>
 	        <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 class="method-example">
 	        <code class="method-declaration">POST https://thedomainname/api/v1/authentication?username={username}&password={password}</code>

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;}
 
 

APIFolder/docUpdateComments.txt

@@ -1,71 +1,72 @@
-Lost permissions again... restore fixed it up... must be some prob with permissions/roles maintenance
+POSSIBLE CHANGES TO APP OR DOCUMENTATION
-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?
-
 
 
 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
+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"
-Formatted field still there DOING
+
+
+loan template - repaymentSchedule is null - I can't see it set in the app
+
 
 loan retrieve DOING
-break up data into categories.. e.g. 
+   break up data into categories.. e.g. 
-Basic - lifeCycleStatusText thru
+   Basic - lifeCycleStatusText thru
-Convenience - open thru waitingForDisbursal then maxSubmittedOnOffsetFromToday, maxApprovedOnOffsetFromToday , maxDisbursedOnOffsetFromToday, actualLoanTermInDays, actualLoanTermInMonths,  loanTermInDays, loanTermInMonths
+   Convenience - open thru waitingForDisbursal then maxSubmittedOnOffsetFromToday, maxApprovedOnOffsetFromToday , maxDisbursedOnOffsetFromToday, actualLoanTermInDays,    actualLoanTermInMonths,  loanTermInDays, loanTermInMonths
-Permission - undoDisbursalAllowed, waiveAllowed, makeRepaymentAllowed, rejectAllowed, withdrawnByApplicantAllowed, undoApprovalAllowed, disbursalAllowed, anyActionOnLoanAllowed
+   Permission - undoDisbursalAllowed, waiveAllowed, makeRepaymentAllowed, rejectAllowed, withdrawnByApplicantAllowed, undoApprovalAllowed, disbursalAllowed, anyActionOnLoanAllowed
-
+   flatten loadData
-flatten loadData
+       repaymentSchedule
-repaymentSchedule
+       summary
-summary
+       loanRepayments
-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.</u></p><p><b>exception</b> <pre>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
 
 
+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.</u></p><p><b>exception</b> <pre>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);
-LOAN TRANSACTIONS (repay and waive - and maybe reversal - but not disbursement) general talk needed as retrieve could work for any txn?
+    Create - (command has string and proper value fields... so assume its like eventDate above)
-transaction type... UNKNOWN(0), DISBURSEMENT(1), REPAYMENT(2), REVERSAL(3), WAIVED(4);
+    If you undo disbursal does it undo the loantransaction? - didnt test
-Create - (command has string and proper value fields... so assume its like eventDate above)
+    Template - does waiver amount default to 'rest of loan' cos it looked like it missed out on other waivers. didn't test
-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.</u></p><p><b>exception</b> <pre>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:
+BUT NOT FOR NOWS
-when adjusting a disbursal - The server encountered an internal error () that prevented it from fulfilling this request.</u></p><p><b>exception</b> <pre>java.lang.IllegalArgumentException: Only repayment and waiver transactions can be adjusted.
+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