From 8321dc7c4d40cf54b6beba69722eb60c547f0e08 Mon Sep 17 00:00:00 2001 From: Keith Woodlock Date: Mon, 4 Feb 2013 16:47:59 +0000 Subject: [PATCH] update api-docs in prep for demo. --- api-docs/apiLive.htm | 85 +++++++++++++++++++++++++++++++------------- api-docs/apidocs.css | 7 ++++ 2 files changed, 67 insertions(+), 25 deletions(-) diff --git a/api-docs/apiLive.htm b/api-docs/apiLive.htm index b620245e5..6b02693c1 100644 --- a/api-docs/apiLive.htm +++ b/api-docs/apiLive.htm @@ -47,6 +47,20 @@ function clickAPILink(apiLink) else window.open(currentLink); } +function clickAPILinkNotPretty(apiLink) +{ + var fixedQueryParams = "tenantIdentifier=default"; + var currentLink = baseURL + apiLink; + if (apiLink.indexOf("?") < 0) currentLink += "?" + fixedQueryParams; + else currentLink += "&" + fixedQueryParams; + + + if ((/MSIE (\d+\.\d+);/.test(navigator.userAgent)) || (apiLink.indexOf("exportCSV") > -1) || (apiLink.indexOf("type=CSV") > -1) || (apiLink.indexOf("type=XLS") > -1) ) + { // test for MSIE (not a great browser for the api docs anyhow) or a file download + location.href = currentLink; + } + else window.open(currentLink); +} function getBaseURL(docURL) { @@ -350,11 +364,10 @@ function getBaseURL(docURL)

Mifos X API Documentation

Mifos X is a secure, multi-tenanted microfinance platform.

The goal of the Mifos X API is to empower developers to build apps on top of the Mifos X Platform. - The - reference Individual Lending app (user: mifos password: password) works on the same demo 'tenant' as the interactive links in this documentation.

+ The reference app (username: mifos, password: password) works on the same demo 'tenant' as the interactive links in this documentation.

The API is organized around - REST. + REST.

The API is designed to have:
@@ -364,16 +377,15 @@ function getBaseURL(docURL) HTTP verbs, which can be understood by off-the-shelf HTTP clients.

-

JSON is returned in all responses from the API, including errors. +

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. + 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.

- -   +  

Try The API From Your Browser

@@ -382,7 +394,7 @@ function getBaseURL(docURL) 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

+ install a REST plugin for your browser e.g. RESTClient for FireFox

The REST plugins will allow you to
  • Select the "Verb" (e.g. POST)
    • @@ -393,9 +405,7 @@ function getBaseURL(docURL)
  • Send the Request (and receive a Response)
-
-  
@@ -413,13 +423,19 @@ function getBaseURL(docURL)

Restrict Returned Fields

Parameter "fields={fieldlist}" can be used on GET requests to restrict the fields returned.

-

Example Request:

-
offices/1?fields=id,name,parentName
+

Normal Request:

+
offices/1
+

+

Request (restricting fields returned):

+
offices/1?fields=id,name

Pretty JSON Formatting

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

+

Normal Request (with pretty printing/formatting):

+
offices/1?pretty=true
+

@@ -446,18 +462,20 @@ function getBaseURL(docURL)

Updating Dates and Numbers

Dates

-

Dates are returned in GET requests as an array e.g. [ 2007, 4, 11]. However, they are sent as strings in POST and PUT requests. - If there are any dates in your POST or PUT requests, you need to provide the "dateFormat". +

Dates are returned in GET requests as an array e.g. [ 2007, 4, 11]. However, the API accepts them as strings in POST and PUT requests. + If there are any dates in your POST or PUT requests, you need to provide the "locale" and "dateFormat". This can be any date pattern supported by Joda-Time. This capability can help you when saving data in your client application as you shouldn't need to do any date format conversion prior to issuing your POST or PUT request.

JSON examples: { + "locale": "en_US", "dateFormat": "dd MMMM yyyy", "openingDate": "01 July 2007" } { + "locale": "en_US", "dateFormat": "yyyy-MM-dd", "openingDate": "2007-03-21" } @@ -3530,24 +3548,37 @@ Request Body:
POST https://Domain Name/api/v1/authentication?username={username}&password={password} -POST authentication?username=super1&password=demo +POST authentication?username=mifos&password=password Content-Type: application/json No Request Body { - "username": "super1", - "userId": 2, - "base64EncodedAuthenticationKey": "c3VwZXIxOmRlbW8=", - "authenticated": true, - "permissions": [ - "USER_ADMINISTRATION_SUPER_USER_ROLE", - "REPORTING_SUPER_USER_ROLE", - "PORTFOLIO_MANAGEMENT_SUPER_USER_ROLE", - "ORGANISATION_ADMINISTRATION_SUPER_USER_ROLE" - ] + "username": "mifos", + "userId": 1, + "base64EncodedAuthenticationKey": "bWlmb3M6cGFzc3dvcmQ=", + "authenticated": true, + "permissions": [ + "ALL_FUNCTIONS" + ] }
+
+ POST https://Domain Name/api/v1/authentication?username={username}&password={password} +POST authentication?username=mifos&password=fail +Content-Type: application/json +No Request Body + +{ + "developerMessage": "Invalid authentication details were passed in api request.", + "developerDocLink": "https://github.com/keithwoodlock/mifosx/wiki/HTTP-API-Error-codes", + "httpStatusCode": "401", + "defaultUserMessage": "Unauthenticated. Please login.", + "userMessageGlobalisationCode": "error.msg.not.authenticated", + "errors": [] +} + +
@@ -4140,6 +4171,10 @@ $(document).ready(function() { clickAPILink($(this).text()); }); + $('.apiClickNotPretty').bind('click', function() { + clickAPILinkNotPretty($(this).text()); + }); + baseURL = getBaseURL(window.location.href); }); diff --git a/api-docs/apidocs.css b/api-docs/apidocs.css index 2f787fd41..ff0a0a184 100644 --- a/api-docs/apidocs.css +++ b/api-docs/apidocs.css @@ -5,6 +5,13 @@ color: blue; } +.apiClickNotPretty { + text-decoration: underline; + cursor: hand; + cursor: pointer; + color: blue; +} + #jpw { text-decoration: underline; cursor: hand;