This page is intended for users with some development experience who are trying to introduce themselves to the basics of writing clients for the MIP Advance REST API.
Client programs communicate with the MIP Advance API by means of HTTP requests and responses. You can write a client for the API in virtually any language that provides a command or library for issuing HTTP requests. The syntax of the client-side code can vary widely depending on the language and library used, but these variations are irrelevant to the API server, which receives only the end result: a formatted message with the following basic elements.
| Verb | The action to be taken at the HTTP level. All MIP Advance API calls are based on one of four HTTP verbs: GET, POST, PUT, and DELETE. Many sources refer to these as "HTTP methods," but we use the less-common term "HTTP verbs" in our documentation in order to avoid confusion with API methods. |
| URL | The URL of the web resource to which the request should be applied. Each method of the API corresponds to a unique pairing of an HTTP verb and a URL. Note that a given URL may service more than one API method if different verbs are used; for example, requests to "Get an account" and "Delete an account" are sent to the same URL, but with different verbs (GET and DELETE respectively). |
| Headers |
A set of key/value pairs that specify additional information needed for the API to process the request. Headers required by the MIP Advance API are:
|
| Parameters | Data that is passed into the API method; for example, a segment ID and account number might be the parameters for an account operation, while a JSON object containing a set of credentials is the single parameter for a login request. Simple string parameters are generally included in the URL, while more complex parameters appear in the request message body as JSON objects. Not all MIP Advance API methods use parameters; see the reference documentation for details. |
As mentioned above, the syntax of an API call in your client code depends on the specific programming language you are using. If your client program is written in Java, your API calls may look very different from how they would look in C++ or JavaScript. In the examples below, we use cURL (a simple command-line tool for data transfer using various protocols) and jQuery to illustrate both the similarities and the differences that can exist between client-side HTTP request implementations. For details of how to construct an HTTP request in the language of your choice, please consult your reference manual.
Important! These code samples are chosen for their relative simplicity, and are included for learning purposes. They should not be regarded as recommended syntax for production use.
The examples below are based on an API server host of http://localhost:9001, which is the default location for an on-premises installation of the MIP Advance server.
One of the simplest method calls for the MIP Advance API is the Get Organizations call, which has no parameters and does not require an authorization token. Using cURL, an invocation of this method might look like this:
curl -X GET "http://localhost:9001/api/security/organizations"
Note that the HTTP verb ("GET") is the argument to the command-line flag "-X", and the URL is the parameter to the cURL command. This very simple call outputs the payload of the response to the console.
The following code snippet using the jQuery ajax() method produces essentially the same HTTP request, and also includes logic for handling the results:
$.ajax({
method: "GET",
url: "http://localhost:9001/api/security/organizations",
success: function (data, status, jqXHR) {
// Code to process successful result
},
error: function (jqXHR, status) {
// Code to process error
}
});
In this case, the HTTP verb and URL appear as fields of the JSON object that the function accepts as a parameter.
Suppose you want to use the Create a Transaction Entry Session API method to create a budget session with a status of Batch-to-Suspend (BS). This method has both a URL parameter to indicate the transaction type and a JSON body parameter containing the specifications for the new session to be created. The HTTP request also requires two headers: "Content-Type," which specifies the format of the body parameter, and "Authorization-Token," which contains the token returned by a recent successful login operation. The following cURL code generates the appropriate HTTP request (white space added for clarity):
curl -X POST --header "Content-Type: application/json" --header "Authorization-Token: 824919926CFC4F8D94586815EF1A8270" -d "{
\"fields\": [
{\"SESSION_SESSIONNUMID\": \"95\"},
{\"SESSION_STATUS\": \"BS\"},
{\"SESSION_DESCRIPTION\": \"Sample Session\"},
{\"SESSION_SESSIONDATE\": \"2016-04-29\"},
{\"SESSION_BUDGET_VERSION\": \"Original\"}
]
}" "http://localhost:9001/api/te/BD/sessions"
Here again, the verb (POST) is the argument to the "-X" command-line flag, and the URL is the parameter to the cURL command. The two headers are specified as key-value pair arguments to the "--header" command-line flag. The JSON object to be included in the HTTP request body is the argument to the "-d" command-line flag.
The following code snippet using the jQuery ajax() method produces a similar request:
$.ajax({
method: "POST",
url: "http://localhost:9001/api/te/BD/sessions",
data: JSON.stringify({
'fields':[
{'SESSION_SESSIONNUMID': '309'},
{'SESSION_STATUS': 'BS'},
{'SESSION_DESCRIPTION': 'Sample X'},
{'SESSION_SESSIONDATE': '2016-04-29'},
{'SESSION_BUDGET_VERSION': 'Original'}
]
}),
headers: {
"Authorization-token": "A54CC5B59248C8663DC758062C6A3890",
"Content-Type": "application/json"
},
success: function(data, status){
// Code to process successful result
},
error: function(status) {
// Code to process error
}
});
Once again, the HTTP verb and URL are fields of the JSON object accepted by the function. The body parameter and headers required for the API method are also included as "data" and "headers" respectively.