IBM Support

Using REST API Details

Technical Blog Post


Abstract

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.

 
This blog adds to other Maximo blog entries on the REST API including:

Tom Sarasin's overview on what it is and how it can be used
Jenny's details of using REST Calls for log correlation 
 

 
 The REST API is part of the integration framework and can be used to Create, Read, Update and Delete (CRUD) and provides two resource data types: XML or JavaScript Object Notation (JSON) format. By default, the system is set up to use XML.
 
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.
 image
 
 
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

 
 Where 1 is the PERSONUID. If referring to a CI object, it would be CIID and not the CINUM; this is actually the unique ID of the table that represents the object.
 
To filter by a specific field, use web-like HTTP arguments. For example:

      http://<your_host_and_port>/maxrest/rest/os/mxperson?displayname=~eq~MAXADMIN&status=~eq~ACTIVE

 
 The display name and status are the fields to filter by. the operator ~eq~ stands for equal. MAXADMIN is the person I'm looking for and I'm also filtering by ACTIVE users. Using the first URL in this post, you can identify all fields that you can use to filter by. There are many operators (like ~eq~) that can be found in the information center reference provided at the beginning of this post, this post is limited to the most basic operations possible through the REST API.
 
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

 
     function requestData() {
      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. 
 
  For additional information, please reference the Maximo Asset Management Information Center located here

[{"Business Unit":{"code":"BU005","label":"IoT"}, "Product":{"code":"SSLKT6","label":"Maximo Asset Management"},"Component":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"","Edition":""}]

UID

ibm11134627