Using REST API Details

Body

The REST (Representational State Transfer) application programming interface (API), is detailed in this blog by Leandro Cassa.  The REST API provides a ways for external applications to query and update application data in Maximo.  Using the REST API is simple and requires no configuration - and it is ready for you to use after installing Maximo.

Tom Sarasin's overview on what it is and how it can be used
 
It uses serializer classes registered in the System Properties (Go To > System Configuration > Platform Configuration > System Properties) as follows:

    mxe.rest.serializer.mbo.xml
    mxe.rest.serializer.os.xml
    mxe.rest.serializer.mbo.json
    mxe.rest.serializer.os.json

The XML output is similar to the integration framework format. And it is possible to extend the existing serializers to generate different outputs.
 
To see the REST API working is just a matter of typing a URL on the browser. For example, try the following URL:

    http://<your_host_and_port>/maxrest/rest/os/mxperson

The URL above returns the list of person records on the target system.
   
The URI (Uniform Resource Identifier) have three parts: maxrest/rest which stands for the REST API reference os which means Object Structure is the resource being used, in this case you could also have mbo for the Business Object resources mxperson which is the object being used.
 
In this post we only use os resource, you can find all available Object Structures under your system at Go To > Integration > Object Structures or even create a new one yourself.
 
Notice that the system requested your user and password. This post assumes you are using the system administrator and therefore you should have full access to the records. The process automation engine provides different security options for the REST API. Refer to the information center provided earlier for more information.
 
It is possible as well to get the output for a single record, as shown in the following example:

    http://<your_host_and_port>/maxrest/rest/os/mxperson/1

 
To filter by a specific field, use web-like HTTP arguments. For example:


 
The following script shows how you could use simple Javascript to interact with process automation engine-based systems' REST API. It is important to understand that any programming language can be used, since it supports the HTTP protocol

      var request = new XMLHttpRequest();
      // set your hostname here
      var host = "http://<your_host>";
      // set your REST URI here
      var uri = "/maxrest/rest/os/mxperson";
      // your query parameters
          var parameters = "PERSONID=~eq~MAXADMIN";
      // defines which function is called when state change
      request.onreadystatechange = state_change;

      request.open("GET", host + uri + "?" + parameters, true);
      // send authorization credentials, base64 encoded for "maxadmin:maxadmin"
      request.setRequestHeader("Authorization", "Basic " + "bWF4YWRtaW46bWF4YWRtaW4=");

      request.send();
       
      function state_change() {
        if (request.readyState == 4) { // 4 = "loaded"
          if (request.status == 200) { // 200 = OK
              // get the XML root element
              var root = request.responseXML.firstChild;
              // get all the tags named DISPLAYNAME
              var displayNameTags = root.getElementsByTagName("DISPLAYNAME");
              // gets the first displayName tag value
              var displayName = displayNameTags[0].firstChild.nodeValue;
              alert(displayName);
            }
            else {
              alert(request.status + " - " + request.statusText);
          }
        }
      }
    }


 Be aware that the code above is not going to work if the script is not on the same domain as your Maximo-based system. By default, web servers do not accept cross-site scripts and HTTP requests. You might not hit this issue if you are using a language other than Javascript.

 
By modifying the script above you can play with the XML results using Javascript DOM API, with the URI through the uri variable defined and with the parameters, using the parameters variable.  This post only covers the Read part of CRUD. To create, update and delete records you must use the http POST method.