Querying Maximo using the REST and JSON APIs

In a recent exchange on the IBM developerWorks forum for Maximo, it was discussed how best to query Maximo through the Integration Framework that is configured for LDAP. Getting data from an LDAP-based Maximo is similar to an environment that is configured to use native authentication, with a few subtle differences. This article will demonstrate how to query for data using the REST API that is found in Maximo 7.5.0.3 and higher, and the JSON API that is found in Maximo 7.6.0.2 and higher.

The information detailed below is available in an IBM article (available as a PDF or as a web page) titled “Maximo NextGen REST API”. Based on questions I have received from our customers and other Maximo professionals, there seems to be some confusion on how to use this information.

There are many tools available that will facilitate communication to and from Maximo using the REST and JSON APIs. This article uses the Postman application which can be downloaded for free here.

Before we dive into the “How” we should discuss the “Why”. What are some reasons for wanting to use these Maximo APIs? Here are a few:

  • Creating new records
  • Modifying existing records
  • Querying Maximo data from an external application
  • Performing calculations on Maximo data such as averaging a cost, finding maximum cost or summing a budget from an external application
  • Creating lists based on Maximo data
  • Querying related records from an external application such as retrieving a list of work orders for a given asset
  • Deleting data
  • Replacing data

Querying Maximo Data with Native Authentication

Let’s start off with a simple scenario: show me all Person records that start with the string ‘CAR’. Note that we are using the Maximo demonstration data for these examples.

To start, we need two pieces of information to complete a successful API call:

  1. Maximo API URL
  2. Maximo Username and Password

However, just having the Maximo Username and Password is not good enough to make an API call. We’ll need to encode those credentials before calling the API.

The credentials will need to be Base64 encoded using the username:password format. For example, if your credentials were maxadmin:maxadmin, your Base64 encoded credentials would be bWF4YWRtaW46bWF4YWRtaW4=. You can use this online utility to perform a successful encode. Place your username:password in the first box and click the > ENCODE < button. Your Base64 encoded string will appear in the box below.

Now we can fire up our Postman application to perform the calls to Maximo.

JSON API

For the JSON API, our Maximo URL will look like this:

http://maximo_host/maximo/oslc/os/mxperson?oslc.where=personid="CAR%"

Substitute your Maximo host name for the maximo_host, and include a port number if necessary.

Next, we’ll need to supply the credentials as an HTTP Header. The header key for Native Maximo Authentication is maxauth. The header value will be your Base64 encoded credentials. Finally, we’ll use the HTTP Method of GET. It comes together like this:

GET http://maximo_host/maximo/oslc/os/mxperson?oslc.where=personid="CAR%"
maxauth: bWF4YWRtaW46bWF4YWRtaW4=

In Postman:

Maximo will perform a wildcard search so all person records that contain the string CAR will be returned. In the case of the sample or demonstration data, that is one record.

The result will be something similar to this:

{
  "member": [
    {
      "href": "http://maximo_host/maximo/oslc/os/mxperson/_Q0FSU09O"
    }
  ],
  "responseInfo": {
    "href": "http://maximo_host/maximo/oslc/os/mxperson?lean=1&oslc.where=personid=%22CAR%25%22"
  },
  "href": "http://maximo_host/maximo/oslc/os/mxperson"
}

When using the JSON API you will get a URI back. This URI is especially useful as you can use this URL to query, perform updates, or perform a delete action on a specific record. In this case you can take the URL and place that back into Postman to perform a GET action. You will receive all of the pertinent record information for that specific record.

http://maximo_host/maximo/oslc/os/mxperson/_Q0FSU09O

REST API

For the REST API, our Maximo URL will look slightly different; however, the concept of authentication remains the same. Substitute your Maximo host name for the maximo_host, and include a port number if necessary:

http://maximo_host/maxrest/rest/os/mxperson?personid=CAR%

It comes together like this:

GET http://maximo_host/maxrest/rest/os/mxperson?personid=CAR%
maxauth: bWF4YWRtaW46bWF4YWRtaW4=

In Postman:

The results are:

{
  "QueryMXPERSONResponse": {
    "rsStart": 0,
    "rsCount": 1,
    "MXPERSONSet": {
      "PERSON": [
        {
          "rowstamp": "[0 0 0 0 0 106 -81 -98]",
          "ACCEPTINGWFMAIL": true,
          "ADDRESSLINE1": "62 Winthrop Street",
          "BIRTHDATE": "1962-08-22T00:00:00-04:00",
          "CITY": "Medford",
          "COUNTRY": "US",
          "DISPLAYNAME": "Tara Carson",
          "FIRSTNAME": "Tara",
          "HIREDATE": "1997-08-01T00:00:00-04:00",
          "LASTEVALDATE": "2001-08-01T00:00:00-04:00",
          "LASTNAME": "Carson",
          "LOCTOSERVREQ": true,
          "NEXTEVALDATE": "2002-08-01T00:00:00-04:00",
          "PERSONID": "CARSON",
          "PERSONUID": 21,
          "POSTALCODE": "02155",
          "PRIMARYEMAIL": "tara.carson@helwig.com",
          "PRIMARYPHONE": "781-555-6247",
          "STATEPROVINCE": "MA",
          "STATUS": "ACTIVE",
          "STATUSDATE": "2003-09-25T15:44:38-04:00",
          "STATUSIFACE": false,
          "TRANSEMAILELECTION": "NEVER",
          "WFMAILELECTION": "PROCESS",
          "PHONE": [
            {
              "rowstamp": "[0 0 0 0 0 96 57 -106]",
              "ISPRIMARY": true,
              "PHONEID": 145855,
              "PHONENUM": "781-555-6247",
              "TYPE": "WORK"
            }
          ],
          "EMAIL": [
            {
              "rowstamp": "[0 0 0 0 0 93 114 125]",
              "EMAILADDRESS": "tara.carson@helwig.com",
              "EMAILID": 145855,
              "ISPRIMARY": true,
              "TYPE": "WORK"
            }
          ]
        }
      ]
    }
  }
}

To get information about a single record in the REST API, you need to reference the Unique ID of the record. In this example, since we are referencing the PERSON object, the PERSONUID attribute is our Unique ID. To query for a specific Person record, include the PERSONUID in the URL:

http://maximo_host/maxrest/rest/os/mxperson/88?_format=json&_compact=1

Querying Maximo Data with LDAP Authentication

If your Maximo instance is configured to use LDAP Authentication, you must use a slightly different HTTP Header to supply the appropriate Maximo credentials. The other information, such as the URL and HTTP Method, remain the same.

In place of MAXAUTH, Authorization is used as the property in the HTTP Header. The same Base64 encoded username:password combination created earlier is also used for the value, however, this time it is preceded with the word Basic and a space character.

It comes together like this using the JSON API:

GET http://maximo_host/maximo/oslc/os/mxperson?oslc.where=personid="CAR%"
Authorization: Basic bWF4YWRtaW46bWF4YWRtaW4=

In Postman:

Similarly, for the REST API:

GET http://maximo_host/maxrest/rest/os/mxperson?personid=CAR%
Authorization: Basic bWF4YWRtaW46bWF4YWRtaW4=

Maintaining Your Session

Once you establish a successful connection to Maximo, you will receive a cookie back in the response with a JSESSIONID token.

It is recommended to use this token in subsequent requests back to the Maximo API. This will improve performance and limit the number of sessions that Maximo creates.

Please feel free to leave any comments or questions below. For visual instruction of the previous steps, check out our video tutorial.