Here is an exclusive look at what I’ve found within Maximo’s integration framework. You won’t find this anywhere else on the web as this stuff is not documented by IBM for Maximo. The REST API can be found in Maximo versions 7.1.1.6 and up including Maximo 7.5. If you look in the directories where you build your maximo.ear files (SMP/maximo/applications/maximo/maxrestweb/), you should be able to see a new file called maxrestweb.war. This is where all the magic happens begins.

I’m sure most of you are already aware of the now old fashioned regular Maximo Integration Framework web services where you use plain old SOAP messages to send to Maximo. Well REST web services don’t use SOAP message to pass data. REST stands for Representational State Transfer and it’s a stateless, client-server protocol.

REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.

• In many ways, the World Wide Web itself, based on HTTP, can be viewed as a REST-based architecture.

RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.

REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP, WSDL, et al.). Later, we will see how much more simple REST is.

• Despite being simple, REST is fully-featured; there’s basically nothing you can do in Web Services that can’t be done with a RESTful architecture.

REST is not a “standard”. There will never be a W3C recommendataion for REST, for example. And while there are REST programming frameworks, working with REST is so simple that you can often “roll your own” with standard library features in languages like Perl, Java, or C#. [via Elkstein.org]

You can always learn more about REST and how to use it by searching the web, but this post is about Maximo’s REST API and how to use it. Now on to the good stuff…

First Look at the REST URL

So how do you access the REST API to query data? It’s simple, here is the structure of the REST URLs used for a query request.

http://localhost:9080/maxrest/rest/os/osname/id?_sattr&attr1=x&attr2=y

So what the heck does all this mean and how I use it? Well, let’s break it down:

• http://localhost:9080 is self explanatory, it’s just your server name and port number
• /maxrest/rest is a fixed path to the REST API servlet
• /os is the prefix for the object structure query
• /osname is the name of the object structure as defined in the Object Structure application
• /id is the unique ID of the top level MBO
• ? is the delimiter to pass attributes
• _sattr are REST specific system attributes that are used to modify the request (Read: REST Reserved Attributes)
• attr1=x&attr2=y are the QBE (Query By Example) query attributes

This is a set of REST reserved attributes that are a part of the REST URL. All of them start with an underscore.

• _format – specifies the format of the response. By default, the two supported values are json and xml.
• _dropnulls – a Boolean value. Set it to true or 1 to drop all null-valued attributes from the response. The default is 1.
• _rootonly – a Boolean value. Set it to true to serialize only the root (primary) object of the object structure. This attribute is valid only for the “os” resource type. The default is 0.
• _locale – a Boolean value. Set it to true to add the user’s locale-specific text version of the MBO attribute to the strong-typed value.
• _keys – a Boolean value. Set it to true to serialize only the key attributes of the MBO and drop all other attributes from the response. The default is 0.
• _rsStart – a numeric value. It indicates the start index of the MBO in the MBOSet resource that is serialized as part of the response for the resource request.
• _maxItems – a numeric value. It indicates the maximum number of MBOs that are serialized in the MBOSet resource that is serialized as part of the response for the resource request. In conjunction with the _rsStart, this attribute can be used for paging the response when the response is too big.
• _includecols – a comma-separated list of MBO attributes that are included as part of the response. All other attributes are dropped. This attribute is valid only for the “MBO” resource type as the “os” resource type has the include/exclude value predefined in the object structure configuration.
• _excludecols – a comma-separated list of MBO attributes that are excluded as part of the response. This attribute is valid only for the “MBO” resource type as the “os” resource type has the include/exclude value predefined in the object structure configuration.
• _lid / _lpwd – the login ID and password. This attribute is used primarily for testing purposes as the credentials passed around as the part of the URL query string potentially create security hazards. This attribute is valid only when the Maximo authentication is used. The preferred way is to use the MAXAUTH header that contains the base64 encoded “userid : password” for the Maximo authentication. Since the server side maintains the session, this value only needs to be provided only on the first request. For j2ee-based authentication, use the basic authentication header.
• _exactmatch– a Boolean value. If it is set to 1, it uses the QBE values as an exact match instead of performing a “like” operation. The default is 0.
• _orderbyasc / _orderbydesc – a comma-separated list of MBO attributes that are used for the order by clause when performing a query.
• _generic – a Boolean value. Set it to 1 to serialize the resource (response) in a generic format. Valid only for the “json” format.
• _md – a Boolean value. Set it to 1 to serialize the resource (response) including the metadata information for each attribute. Example: ResourceId, Hidden, Read-only.
• _compact – a Boolean value. Set it to 1 to serialize the resource (response) in a very compact JSON format. In addition, the attribute sets _md to 0 and _generic to 0 and is only valid for the JSON format.
• _opmodeor – a Boolean value. Set it to 1 to pair together the attribute operator values used for filtering the query.
• _fd – specifies the table domain that filters the main object. The table domain is used to filter the main object in the REST query. The object must be the same as the main object to query. Set this attribute to true to use the list with the clause and the QBE is used to retrieve the result set. This list can only contain plain SQL. There is one addition, the “:user” attribute that contains the name of the user that is currently logged on. A table domain can contain different definitions based on site and og values. These two values are specified by the _fdsite and _fdorg attributes.
• _fdsite – specifies the site value for the _fd query.
• _fdorg – specifies the org value for the _fd query.

Restricting resource sets with QBE filtering

The supported syntax is Attribute=Operator Value:

• = value. Attribute is like value.
• =~eq~ value. Attribute equals value.
• =~neq~ value. Attribute does not equal value.
• =~gt~ value. Attribute is greater than value.
• =~gteq~ value. Attribute is greater or equals value.
• =~lt~ value. Attribute is less than value.
• =~lteq~ value. Attribute is less or equals value.
• =~ew~ value. Attribute ends with value.
• =~sw~ value. Attribute starts with value.

In the next few tutorials, I will be showing you how to query and send data to this REST API….