REST API
Documentation

Tutorial 1: A Simple API Call

Note: This tutorial is designed for on-premises installations of the MIP Advance API service. If you have access to the API only in hosted mode, please proceed to Tutorial 2B, "Logging In (Hosted)."

As your first tutorial exercise, you will create and run an HTML/jQuery code file invoking the simplest method of the MIP Advance API: Get Version. This method has no required headers and no parameters; it simply returns a JSON object containing the current version of the MIP Fund Accounting program.

The Get Version Call

Please be aware that the sample code is simplified for clarity, and should be used for learning purposes only.

Type the following code into your text editor, substituting the URL of your on-premises API service for [[REST_URL]]. For example, a default on-premises installation might have the URL "http://localhost:9001", so that line 7 below would be 'url:"http://localhost:9001/api/security/login"'.

<html>
<head>
   <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.2/jquery.min.js"></script>
   <script>
      $.ajax({
         method: "GET",
         url: "[[REST_URL]]/api/security/version",
         success: function (data, status) {
            alert("MIP version: " + data.version);
         },
         error: function (DATA, status) {
            alert("Error: could not retrieve version number.");
         }
      });
   </script>
</head>
</html>

Save the code as versiontest.html. Open the new file in your web browser. When the request completes, you should see an alert box with content similar to the following:

Congratulations! You've just written your first MIP API client code!

What's Going On?

Because this API call requires no headers or parameters, we only need to specify the URL and the HTTP verb ("GET" in this case). For the jquery ajax() call, these are included as "url" and "method" respectively in the JSON object argument, while the "success" and "error" functions contain the logic to process the result of the request.

The response to your HTTP request includes a status code and (if the request was successful) a data object containing the result: a JSON object with a single member, as shown below.

{version: "17.1.0.0"}

This status code and result are automatically provided to the "success" function as "status" and "data" respectively.

Although other languages and tools may use very different syntax to produce HTTP requests, the essential elements remain the same.