Assetize

Learning Lab

Level 5 · 15 levels · Practitioner · about 85 minutes

Level 5 — The Maximo REST API: read, filter, create and handle errors

By the end: Write Maximo REST calls with confidence: the address, the API key and lean; oslc.select, oslc.where (syntax, operators and quoting), oslc.orderBy, oslc.pageSize and paging; creating with POST and the properties header; updating with x-method-override PATCH, patchtype MERGE and If-Match; actions such as wsmethod:changeStatus; bulk calls; and reading a BMXAA error well enough to fix it.

One work order, four ways to touch it. GET reads it. POST creates a new one. POST with x-method-override: PATCH changes it. An action call runs a named piece of business logic. Every request in this level is one of these four, and every one of them goes through the business rules you met in Level 4.

A work order record card with four actions around it: GET reads it, POST creates a new one, POST with x-method-override PATCH changes it, and an action call such as changeStatus runs business logic.

Lesson 1

The address, the API key and lean

Every Maximo REST call starts with the same address pattern: https://your-maximo/maximo/api/os/ followed by an object structure name. /maximo is the Manage application. /api is the REST route. /os says "object structure". The last part names the bundle you want, such as mxapiwodetail. Upper or lower case both work there; most people write it in lower case.

The parts of a curl command. One curl command, labelled part by part: the program, the apikey header, the address, the object structure name, and the query settings after the question mark.

One curl command with each part labelled in turn: the program curl, -H and the apikey header, the address, the object structure name, and the query settings after the question mark.

PartExampleWhat it means
Hosthttps://your-maximo.example.comWhere your Maximo lives
Route/maximo/apiThe REST route. Use it with API keys.
Object structure/os/mxapiwodetailWhich bundle of objects you are reading or writing
One record/os/mxapiwodetail/_QkVERk9SRC8xMjAxA single record, by the id Maximo gave it
Query settings?lean=1&oslc.select=wonum,statusWhich fields, which rows, how many, in what order

You will also see /maximo/oslc in older code. It is the same API underneath; the difference is how the login is handled. On MAS, /maximo/api is the route that takes an API key directly, so use it for programs.

Every call must say who is calling. Programs send an API key: a long random string created for one Maximo user. IBM documents two ways to send it, as an apikey request header or as an apikey query parameter. Use the header. Addresses are written into server logs, proxy logs and browser history, so a key in the address leaks. A call made with a key runs as that user, with that user's security groups and sites, and it uses a "silent" login: no screen and no session to keep alive.

No key, no data. No key, and the door stays shut: the answer is 401. With a key, the door opens and records come back with 200.

A request walks up to a locked Maximo door. Without a key it bounces back with 401. A valid key for a user without permission gets past the door and stops at the security gate with 403. A good key with the right access gets 200 and the records.

Keys can expire or be revoked. A MAS 9.2 system answers a dead key with "BMXAA9549E - The API key token is invalid. Either the token may have expired or the token has been revoked by the administrator." When you see that, your request is fine; the key is not.

Add lean=1 to every call. Without it, the answer uses the OSLC format, where names carry namespace prefixes such as spi: and oslc:. With it, you get plain JSON names: wonum, status, member. IBM's guide recommends setting lean=1 on all requests, so a request can move to another server during load balancing and still come back the same shape.

Your first real call

export MAXIMO=https://your-maximo.example.com
export MAXIMO_APIKEY=...      # created in the API Keys application; never in code

curl -H "apikey: $MAXIMO_APIKEY" \
  "$MAXIMO/maximo/api/os/mxapiwodetail?lean=1&oslc.select=wonum,status&oslc.pageSize=2"

A lean answer (sample data). STATUS is bound to a domain, so Maximo adds status_description for you.

{
  "member": [
    { "wonum": "1201", "status": "WAPPR", "status_description": "Waiting on approval",
      "href": "https://your-maximo.example.com/maximo/api/os/mxapiwodetail/_QkVERk9SRC8xMjAx" },
    { "wonum": "1202", "status": "WSCH", "status_description": "Waiting to be scheduled",
      "href": "https://your-maximo.example.com/maximo/api/os/mxapiwodetail/_QkVERk9SRC8xMjAy" }
  ],
  "responseInfo": { "pagenum": 1, "nextPage": { "href": "…" } }
}

Remember: Start every new integration with one tiny call: oslc.pageSize=1 and two fields. Prove the address, the key and the object structure work before you write a single loop.

The mistake: Paste curl "…/mxapiwodetail?apikey=abc123…" into a ticket so a colleague can try it. Do this instead: Send -H "apikey: $MAXIMO_APIKEY" and keep the value in an environment variable. A key in an address or a ticket is a leaked key.

Lesson 2

Pick the fields and the rows: oslc.select and oslc.where

oslc.select names the fields you want back, separated by commas: oslc.select=wonum,description,status,assetnum. Reach into a child list with braces: wplabor{craft,laborhrs}. Reach through a relationship with a dot: asset.description gives each work order's asset description. A one-to-many relationship uses rel.: IBM's example is rel.openwo{wonum,description} on an asset. Empty fields are left out of the answer; add _dropnulls=0 when you need to see them.

oslc.where filters the rows inside Maximo, before anything is sent to you. IBM's guide says it maps onto Maximo's own query framework, the same one behind the search fields on a list screen. It can filter on any persistent attribute of the main object, or of a related object through a relationship, such as location.status="OPERATING" on assets.

OperatorMeansExample
=equalsstatus="APPR"
!=not equalwopriority!=1
> >=greater than (or equal)wopriority>=2
< <=less than (or equal)reportdate<"2026-10-01T00:00:00+10:00"
inany value in a liststatus in ["APPR","INPRG"]
andboth conditions must holdstatus="APPR" and siteid="BEDFORD"
"%text%"contains ("text%" starts with, "%text" ends with)description="%leak%"
="*"has a value (not null)assetnum="*"
!="*"is empty (null)assetnum!="*"

Quoting follows the data type, and IBM's guide says the language is data type sensitive. Text and dates go in double quotes: status="APPR". Dates are ISO strings with a time zone, such as "2026-10-01T00:00:00+10:00". Numbers take no quotes: wopriority=1. Yes or no fields take 1 or 0, or true or false, with no quotes: istask=0. Get the quoting wrong and the filter will not do what you meant.

IBM's guide joins conditions with and. When you want "this value or that value" on one field, use in: status in ["APPR","INPRG"].

Build a REST query. Tick a field and watch oslc.select grow. Pick a status and watch oslc.where change. The little table shows only what you asked for.

An interactive query builder: tick fields to select, pick a status to filter on and a page size. The address builds itself as you click, and a small result table changes to match.

In a real HTTP request, spaces and quotes inside the address must be URL-encoded: a space becomes %20 and a double quote %22. HTTP libraries in your code do this for you. In curl, either wrap the whole address in double quotes and escape the inner quotes with a backslash, as the sim missions do, or let curl encode each setting with -G and --data-urlencode.

oslc.where in practice

# Approved or in-progress work at one site, priority 1 or 2, newest first
curl -G -H "apikey: $MAXIMO_APIKEY" "$MAXIMO/maximo/api/os/mxapiwodetail" \
  --data-urlencode 'lean=1' \
  --data-urlencode 'oslc.select=wonum,description,status,wopriority,asset.description' \
  --data-urlencode 'oslc.where=siteid="BEDFORD" and status in ["APPR","INPRG"] and wopriority<=2' \
  --data-urlencode 'oslc.orderBy=-reportdate' \
  --data-urlencode 'oslc.pageSize=20'

# The same idea in the sim, with the inner quotes escaped
curl -H "apikey: $apikey" "/maximo/api/os/mxapiwodetail?oslc.where=status in [\"APPR\",\"INPRG\"]&oslc.select=wonum,status"

One rule catches everyone once: oslc.where works on persistent attributes only. Ask MXAPIINVENTORY for curbaltotal>0 and a MAS 9.2 system answers 400 with "BMXAA4185E - Cannot query on field CURBALTOTAL." Current balance is computed by the MBO, not stored. You can select it; you cannot filter on it. Filter on a stored field instead.

Synonym statuses need care too. status="APPR" matches the value APPR only, not a synonym such as WPCOND. IBM's guide describes domaininternalwhere for this: it filters on the internal values of a synonym domain, for example domaininternalwhere=status!=APPR,INPRG, and it is joined to your oslc.where with and.

The mistake: Fetch every work order and filter in your own code. Do this instead: Filter with oslc.where so Maximo sends only the rows you need. One MAS 9.2 demo system we read holds more than 67,000 work orders; a real customer can hold many more.

Lesson 3

Sort and page through big answers

oslc.orderBy sorts the answer. Every field in it starts with a sign: - for high to low, + for low to high, separated by commas, as in oslc.orderBy=-reportdate,+wonum. IBM's guide adds two catches. The + sign must be URL-encoded as %2B, because in an address a bare + means a space. And you can sort only on persistent attributes of the main object. There is no default order, so if order matters, ask for it.

oslc.pageSize sets how many records come back in one answer. The answer then carries a responseInfo block next to member, with pagenum and links called nextPage and previousPage. To read everything, follow nextPage.href until there is no nextPage. Do not build page addresses yourself; follow the link Maximo gives you.

Build a REST query. Set a small page size and watch the table hold only that many rows. The rest wait behind the next page link.

An interactive query builder: tick fields to select, pick a status to filter on and a page size. The address builds itself as you click, and a small result table changes to match.

A paging loop in TypeScript

// Read every approved work order, 100 at a time
let url = host + '/maximo/api/os/mxapiwodetail?lean=1&oslc.select=wonum,status'
  + '&oslc.where=' + encodeURIComponent('status="APPR"')
  + '&oslc.pageSize=100';
const rows = [];
while (url) {
  const res = await fetch(url, { headers: { apikey: process.env.MAXIMO_APIKEY } });
  if (!res.ok) throw new Error('Maximo answered ' + res.status + ': ' + (await res.text()));
  const page = await res.json();
  rows.push(...page.member);
  url = page.responseInfo?.nextPage?.href;   // no nextPage: that was the last page
}

Maximo protects itself from huge answers. An administrator can set a maximum page size for every object structure (the mxe.oslc.maxpagesize property) or for one of them; ask for more and the request fails with an error. Each object structure can also have an automatic paging threshold, set in the Object Structures application: leave oslc.pageSize out on a big set and Maximo pages for you once the count passes that threshold.

Records can change while you page. If work orders are added between page 1 and page 2, rows shift, and you can see one twice or miss one. IBM's answer is stablepaging=1. Maximo holds your result set and puts a stableId in the nextPage link. Stable paging only goes forward, a page cannot be loaded twice, and the held set expires after five minutes without use or when you reach the end.

JSON as text and as a tree. A lean answer as text and as a tree. member is the list of records on this page; each record is a set of names and values. In a paged answer, responseInfo sits next to member and holds the link to the next page.

A Maximo JSON answer shown as text on the left and as a tree on the right: member is a list holding two work orders, each with wonum and status. Brackets light up as their tree nodes do.

The mistake: Type oslc.orderBy=+wonum straight into an address. Do this instead: Encode the plus as %2B (oslc.orderBy=%2Bwonum), or let your HTTP library build the query. A bare + arrives as a space.

Remember: Asked for 20 and got 20? Check responseInfo for a nextPage before you report "that is all of them".

Lesson 4

Create a record: POST and the properties header

To create a record, POST a JSON body to the object structure's address. The body holds the fields you are setting. Maximo then runs the MBO rules exactly as if a person had filled in the screen: it fills defaults such as the next work order number and the starting status, checks required fields and domains, and saves.

Create a corrective (CM) work order

curl -i -H "apikey: $MAXIMO_APIKEY" \
  -H "content-type: application/json" \
  -H "properties: wonum,status,siteid,href" \
  -d '{"siteid":"BEDFORD","description":"Seal leak on standby pump","assetnum":"11400","worktype":"CM"}' \
  "$MAXIMO/maximo/api/os/mxapiwodetail?lean=1"

The answer (sample data shaped like a MAS 9.2 reply)

HTTP/1.1 201 Created
location: https://your-maximo.example.com/maximo/api/os/mxapiwodetail/_QkVERk9SRC8xMjAx

{ "wonum": "1201", "status": "WAPPR", "siteid": "BEDFORD",
  "href": "https://your-maximo.example.com/maximo/api/os/mxapiwodetail/_QkVERk9SRC8xMjAx" }

A successful create answers 201 Created, with a Location header holding the new record's address. Without the properties header the body is empty: a MAS 9.2 system answered our create with 201 and no body at all. Add properties: wonum,status,href and Maximo sends those fields of the new record straight back. IBM's guide notes that this saves an extra GET after every create and update. properties: * returns everything, but name the fields you need: it is faster.

A request and a response. A POST travels to Maximo with a JSON body and comes back 201 Created. Without a properties header, the status and the Location header are all you get.

A laptop sends a request (method, address, headers, body) across to a server. The server answers with a status code and a body. The packet travels there and back.

A new work order starts in WAPPR, waiting on approval, unless your Maximo is set up otherwise. Read the status from the answer, not from your own assumptions.

Keep the href. It is the record's address for every later read, update or action. The part after the last slash is the rest id. IBM's guide says it is generated from the primary key values and is not the record's unique id: _QkVERk9SRC8xMjAx is base64 for BEDFORD/1201, the site and the work order number. Never build one by hand. Use the href Maximo gives you, or find the record with a query.

Creates are not idempotent. POST the same body twice and you get two work orders, each with its own number. Where you choose the key yourself, such as a new asset number, a second POST fails instead with BMXAA4129E: the record already exists. A POST to the collection always means "create". So before you retry a create after a timeout, search for the record first. Store your own reference on it, for example in an external reference field, so the search is exact.

  • 201 means created. Anything else: read the error body before you do anything.
  • Take values from the properties answer, not from what you sent: Maximo may have filled or changed them.
  • Log the new href with your own reference, so a retry can find the record instead of making a second one.

The mistake: POST again to the collection with the same wonum to "update" a work order. Do this instead: A POST to the collection is always a create. To change a record, POST to its href with x-method-override: PATCH, as the next lesson shows.

Remember: Try the create-wo mission: create a work order on PUMP-102 with work type CM and ask for wonum and status back with the properties header.

Lesson 5

Change a record: PATCH, patchtype MERGE and If-Match

To change a record, POST to its href and add the header x-method-override: PATCH. In IBM's words, x-method-override:PATCH instructs the server side to update the resource. Send only the fields you are changing. Add a properties header if you want the changed record back in the answer.

Approve a work order by changing its status

curl -H "apikey: $MAXIMO_APIKEY" \
  -H "x-method-override: PATCH" \
  -H "content-type: application/json" \
  -H "properties: wonum,status,statusdate" \
  -d '{"status":"APPR"}' \
  "$MAXIMO/maximo/api/os/mxapiwodetail/_QkVERk9SRC8xMjAx?lean=1"

That shape of call, on a MAS 9.2 system, moved a new work order from WAPPR to APPR and answered 200. The same shape then took it to INPRG, COMP and CLOSE, one move at a time. Each move went through the status rules from Level 4, so a move the rules forbid is refused the same way the screen refuses it.

The verbs on a record. The PATCH verb is lit: a POST to the record's own address, with x-method-override: PATCH. Same verb as a create, different address, different header, different meaning.

A work order record card with four actions around it: GET reads it, POST creates a new one, POST with x-method-override PATCH changes it, and an action call such as changeStatus runs business logic.

Child lists need care. When your body includes a child list, such as wplabor, a plain PATCH treats your list as the whole truth. IBM's guide is blunt: in a PATCH request, the server side deletes all child objects that are not in the request payload. Send one planned labour line and the other three are gone. Add the header patchtype: MERGE and Maximo matches children by their keys instead: a match is updated, a new one is added, and the rest are left alone. IBM makes the same point when you add a user to security groups through the API: send patchtype: MERGE, or the user is removed from the groups you did not list.

PATCH with a child list, no patchtypePATCH with patchtype: MERGE
  • Your child list replaces the stored one
  • Children missing from your body are deleted
  • Right only when you mean "this is the full list"
  • Children are matched by their keys
  • Matches are updated, new ones are added
  • Children you did not send stay as they are
AddChange, Sync and Delete. The same idea in the Data Workbench. Sync adds and updates, and also removes child rows missing from your sheet: a plain PATCH with a child list behaves like Sync. MERGE behaves like AddChange.

The same sheet loaded three ways onto a record with child rows. AddChange adds and updates. Sync adds and updates and also removes the child rows missing from the sheet. Delete removes the records.

Two people, or two systems, can change the same record at once. Without protection the last save wins and quietly undoes the first. Maximo's protection is the ETag. When you GET a record, Maximo returns an ETag response header: a version stamp for that record. Send it back on your update in an If-Match header. If someone changed the record after you read it, the stamps differ and Maximo refuses with 412 Precondition Failed. You then read the record again, re-apply your change and try once more. Every object in an answer also carries _rowstamp, which IBM's guide says is used for handling dirty updates.

A safe update with If-Match

# 1. Read, and keep the ETag response header
curl -i -H "apikey: $MAXIMO_APIKEY" "$MAXIMO/maximo/api/os/mxapiwodetail/_QkVERk9SRC8xMjAx?lean=1&oslc.select=wonum,description"
#    ETag: 1234567

# 2. Update only if nobody changed it since
curl -H "apikey: $MAXIMO_APIKEY" -H "x-method-override: PATCH" -H "If-Match: 1234567" \
  -d '{"description":"Seal leak on standby pump, bearing noisy"}' \
  "$MAXIMO/maximo/api/os/mxapiwodetail/_QkVERk9SRC8xMjAx?lean=1"
#    412 Precondition Failed means: someone got there first. Read again.

The mistake: Send the whole record back on every update, child lists and all, without patchtype. Do this instead: Send only the fields you change. Add patchtype: MERGE whenever the body holds a child list, and If-Match whenever someone else may be editing the same record.

Lesson 6

Actions and bulk calls

Some business logic is not a field you can set: approving with a memo, starting a workflow, the steps behind a button. For these, Maximo exposes actions. You call them on a record's href with ?action=<type>:<name>. For Java methods on the object, the type is wsmethod, and the name is the method's name. IBM's guide shows POST <work order href>?action=wsmethod:approve with the body {"memo":"Testing"}. Because an action works on an existing record, IBM says to send x-method-override: PATCH with it. Workflows use the type workflow: ?action=workflow:ABC starts the workflow process named ABC on that record.

Change status through the changeStatus action

curl -H "apikey: $MAXIMO_APIKEY" -H "x-method-override: PATCH" \
  -H "content-type: application/json" \
  -d '{"status":"APPR"}' \
  "$MAXIMO/maximo/api/os/mxapiwodetail/_QkVERk9SRC8xMjAx?lean=1&action=wsmethod:changeStatus"

To see what a record offers, ask for allowedactions: oslc.select=allowedactions on a query. IBM's guide says the answer lists the web methods of the object structure's main object, plus actions registered in the Action Definition application.

The verbs on a record. The action call is lit. It does not set a field: it runs a named piece of business logic on the record, with that logic's own rules.

A work order record card with four actions around it: GET reads it, POST creates a new one, POST with x-method-override PATCH changes it, and an action call such as changeStatus runs business logic.

Status changes can go two ways. IBM's guide shows wsmethod:changeStatus, including in bulk. Many teams simply PATCH the status field, as in the last lesson, and both routes go through the status rules. In an IBM community thread, an experienced Maximo developer recommends the PATCH; one reason he gives is that integration automation scripts cannot intercept a web method call. Whichever you choose, read the answer. A refused move comes back as a 4xx error whose message says why, and the status stays where it was.

The work order lifecycle. The status rules guard every route. Through PATCH or through changeStatus, a work order that is in progress cannot be cancelled: INPRG can go to WAPPR, WMATL, COMP or CLOSE, never CAN.

A work order status machine: WAPPR to APPR to INPRG to COMP to CLOSE, with WSCH and WMATL as side statuses and dashed arrows to CAN from WAPPR and APPR. A token moves along allowed arrows. Once the work order is in progress, an attempt to cancel it is refused and shakes red, and the allowed moves are listed: WAPPR, WMATL, COMP, CLOSE.

When you have many records to load, one call per record is slow. IBM's data import advice is short: use bulk APIs for best performance. A bulk call is a POST to the collection with x-method-override: BULK and a JSON array as the body. Each item carries an _action: Add, Update (with the record's href) or Delete (with its href). One call can mix all three.

One bulk call, three actions

curl -H "apikey: $MAXIMO_APIKEY" -H "x-method-override: BULK" \
  -H "content-type: application/json" \
  -d '[
    {"_action":"Add", "siteid":"BEDFORD", "assetnum":"PUMP-201", "description":"Standby pump 2"},
    {"_action":"Update", "href":"<href of an asset>", "description":"Duty pump 1"},
    {"_action":"Delete", "href":"<href of an asset>"}
  ]' \
  "$MAXIMO/maximo/api/os/mxapiasset?lean=1"

Read a bulk answer carefully. IBM's guide says that unless the JSON itself is broken, a bulk call always answers 200. The real result is per item. Each item comes back with _responsemeta carrying its own status, such as 201, or with _responsedata holding an Error. Maximo commits each item on its own, so some can succeed while others fail. If you need all or nothing, send the header allornothing: 1, and one failure means no record is changed.

  1. POST the array with x-method-override: BULK
  2. Get 200 for the call as a whole
  3. Read every item's _responsemeta.status
  4. Count successes and failures
  5. Fix and resend only the failed items

Reading a bulk answer

The mistake: See 200 on a bulk call and report "all 500 rows loaded". Do this instead: Check every item's status. Count the successes and failures, and retry only the failed rows, the way the Workbench sends committed rows once and retries only the failures.

Remember: Try the illegal-status mission: work order 1003 is already in progress. Try to cancel it with changeStatus, and read the 400 that comes back: it lists the moves that are allowed.

Lesson 7

Read the error, then build good habits

When Maximo refuses, it says why. A refused REST call answers with a 4xx or 5xx status and a JSON body called Error. Here is a real one from a MAS 9.2 system, with the host name hidden. The request tried to set a value that a domain does not allow:

A real Maximo error answer

{
  "Error": {
    "reasonCode": "BMXAA0211E",
    "message": "BMXAA0211E - 1 is not defined in the domain DEFECTCLASS.",
    "statusCode": "400",
    "errorobjpath": "incident/ticketspec",
    "errorattrname": "alnvalue",
    "errattrvalue": null,
    "correlationid": "1",
    "timestamp": "2026-10-17T19:52:48+00:00",
    "extendedError": {
      "moreInfo": { "href": "https://your-maximo/maximo/api/error/messages/BMXAA0211E" }
    }
  }
}
Reading a Maximo error. Each part of a Maximo error, labelled: the HTTP status, the BMXAA reason code, the message in words, and the extended error link.

A Maximo error answer with its parts labelled: the HTTP status 400, the reason code starting with BMXAA, the message in words, and the extended error link.

FieldWhat it tells you
statusCodeThe HTTP status again. 400 means: change your request.
reasonCodeThe message ID: BMXAA, four digits, then E for an error (you will also meet I for information). This is what you look up.
messageThe ID plus the reason in words. Read it twice, word for word.
errorattrname, errorobjpathWhich field, in which object of your body, caused it, when Maximo can tell
extendedError.moreInfo.hrefA link to the message's definition on your own Maximo
Message (real, from MAS 9.2 systems)What it meansWhat you do
BMXAA4190E - Status COMPLETE is not in the value list.The value is not in the domainSend a valid value: COMP, not COMPLETE
BMXAA0211E - 1 is not defined in the domain DEFECTCLASS.The value is not in the domainLook the domain up and send one of its values
BMXAA4195E - A value is required for the … field on the … object.A required field is missingAdd the field to your body
BMXAA4129EThe record already existsYou meant an update: find the record and PATCH its href
BMXAA4185E - Cannot query on field CURBALTOTAL.You filtered on a nonpersistent fieldFilter on a stored field
BMXAA9301EThe user is not authorised for this object structureAsk for object structure access for the integration user
BMXAA4216E - Unknown Object named MXAPIROUTE.That object structure is not on this systemCheck the name in the Object Structures application
BMXAA9549EThe API key is invalid, expired or revokedGet a new key; the request itself is fine
BMXAA7901E - You cannot log in at this time.The login was refusedCheck the user and how you authenticate
  1. Read the status code first. 4xx: your request needs changing. 5xx: the server had a problem.
  2. Read the whole message, word for word. It usually names the field, the value and the object.
  3. Look the code up. The Assetize error lookup explains many BMXAA codes, with their sources.
  4. Decide. A 400 fails the same way every time until you change the request, so fix it and do not retry. A 429 or 503 is worth a retry, after a wait that grows each time.
  5. Log it: method, address without the key, status, reasonCode and message. That one line is what you will need at 2 a.m.

When a create or update has several bad fields, you can see them all at once. IBM's guide describes a request header, batcherror: 1, that batches all the errors together, so you can fix them in one round instead of one at a time.

Status code families. Three families. Green worked. Amber means change your request, except 429, which means slow down and try later. Red means the server had a problem.

Three lanes: 2xx success in green (200 OK, 201 Created), 4xx your request needs changing in amber (400, 401, 403, 404, 429), 5xx server problem in red (500, 503). Each code has a small picture.

Back off and retry. A 429 comes back. The good client waits, then waits longer, with a little randomness, until it gets 200. It never hammers a busy server.

A client gets 429 Too Many Requests and waits before trying again, waiting longer each time with a little randomness, until it gets 200. Beside it, a client that retries instantly makes the storm worse.

HabitWhy
API key in a header, read from an environment variableKeys in addresses and code leak
lean=1 on every callPlain names, and IBM recommends it for load balancing
oslc.select with named fieldsSmall, fast answers
oslc.where on stored fieldsMaximo sends only the rows you need
oslc.pageSize, and follow nextPageBig customers hold tens of thousands of records
properties on create and updateNo extra GET to see the result
patchtype: MERGE with child listsChildren you did not send stay
If-Match when others may editNo silent lost updates
Search before you retry a createA POST sent twice makes two records
A request logThe first thing you want when something breaks

The REST and OSLC API, drawn

The mistake: Retry every failed request three times, whatever the status. Do this instead: Retry only what can succeed later: 429 and 503, with growing waits. Fix and resend a 4xx; it fails the same way until the request changes.

Remember: Most "it is impossible" conclusions come from not reading the error properly. Read it twice. Then try the journal mission: the sim keeps a log of every request you send.

Level 5 missions in the Maximo sim

  1. Raise a corrective work order. Create a work order against asset PUMP-102 with work type CM, and ask Maximo to echo back the number it gave it.
  2. Cancel work that has started. Work order 1003 is in progress. Try to cancel it, then read the error: it lists the moves that are allowed.
  3. Read your own request log. Show the list of every request you have sent in this session.

Real practice on the Maximo SIM

Tasks you do by hand on the training Maximo, with the evidence your trainer checks.

  1. Query the backlog over the API (DEV). The same list you filtered on the screen, now from code: only the fields you need, filtered inside Maximo.
  2. Create a work order over the API (DEV). Integrations create records this way. The properties header asks Maximo to send back the new number.
  3. Make Maximo refuse you, then read the error (DEV). Errors are messages. Learn to read the reason code and the message word for word.

Check yourself: the Level 5 quiz

18 questions. Pass mark 70%.

  1. Look at the lit part of the command. What does it name? (picture: The parts of a curl command)
    • The Maximo server's host name
    • The object structure: the bundle of objects you are reading
    • The API key
    • The page size
  2. Why send the API key as a header instead of an apikey query parameter?
    • Headers are faster
    • Addresses end up in server logs, proxies and browser history, so a key there leaks
    • Query parameters are not allowed on MAS
    • Headers are encrypted and the address is not
  3. What does lean=1 do?
    • Returns fewer records
    • Returns plain JSON names without OSLC namespace prefixes; IBM recommends it on every request
    • Skips the business rules
    • Compresses the answer
  4. Look at the builder. Which setting decides which rows come back? (picture: Build a REST query)
    • oslc.select
    • oslc.where
    • oslc.pageSize
    • lean
  5. Which oslc.where finds approved work orders with priority 1?
    • status=APPR and wopriority="1"
    • status="APPR" and wopriority=1
    • "status"="APPR" & "wopriority"=1
    • status:"APPR",wopriority:1
  6. You want work orders that are either APPR or INPRG. Which filter does that?
    • status="APPR" or "INPRG"
    • status in ["APPR","INPRG"]
    • status="APPR,INPRG"
    • status=["APPR"]+["INPRG"]
  7. You filter MXAPIINVENTORY with oslc.where=curbaltotal>0 and get BMXAA4185E - Cannot query on field CURBALTOTAL. Why?
    • Your key expired
    • CURBALTOTAL is nonpersistent: computed, not stored, so it cannot be filtered on
    • The storeroom is empty
    • oslc.where does not allow >
  8. Your oslc.orderBy=+wonum comes back in no particular order. What went wrong?
    • wonum cannot be sorted
    • The + was read as a space; it must be encoded as %2B
    • You need oslc.pageSize first
    • Sorting only works on dates
  9. How do you read page 2 of a big answer?
    • Add 100 to the record ids
    • Follow responseInfo.nextPage.href from the first answer
    • Send the same request again
    • Ask for a bigger page size than the maximum
  10. Look at the picture. The create worked, but the answer has no body. Why? (picture: A request and a response)
    • The create failed
    • No properties header was sent, so Maximo answered 201 with only a Location header
    • The key is read-only
    • lean=1 removes the body
  11. Look at the lit verb. Which header turns this POST into an update? (picture: The verbs on a record)
    • properties: *
    • x-method-override: PATCH
    • content-type: text/plain
    • apikey: update
  12. You PATCH a work order with a body holding one wplabor line and no patchtype header. It had three lines before. What happens?
    • All four lines are kept
    • The other planned labour lines are deleted; only the one you sent remains
    • The call is refused
    • Nothing changes
  13. You send If-Match with the ETag you read earlier, and the update comes back 412 Precondition Failed. What does it mean?
    • The key expired
    • Someone changed the record after you read it; read it again and re-apply your change
    • The JSON is invalid
    • The record was deleted
  14. Look at the picture. Your code sends this move through the REST API. What comes back? (picture: The work order lifecycle)
    • 200, and the work order is cancelled
    • A 400 error that says why, and the status stays INPRG
    • A 500 every time
    • Nothing at all
  15. IBM's guide shows ?action=wsmethod:approve on a work order href. What else must the request send?
    • x-method-override: PATCH
    • x-method-override: BULK
    • lean=0
    • A DELETE method
  16. A bulk call answers 200. What does that tell you?
    • Every item succeeded
    • The JSON was readable; each item's own _responsemeta.status says whether it worked
    • Nothing was processed
    • All items were rolled back
  17. Look at the error. Which part do you look up first? (picture: Reading a Maximo error)
    • The timestamp
    • The BMXAA reason code
    • The correlation id
    • The host name
  18. Which error is worth retrying after a wait?
    • Code A
    • Code B

Remember it as a picture

  • /maximo/api/os/<object structure>: Every REST call: the Manage application, the REST route, "object structure", then its name.
  • apikey header: One Maximo user's key, sent as a header, read from an environment variable. Runs with that user's access.
  • lean=1: Plain JSON names (wonum, member) instead of prefixed OSLC names. Put it on every call.
  • oslc.select: The fields to return. Braces for child lists, a dot for relationships: wplabor{craft}, asset.description.
  • oslc.where: Filter inside Maximo. Text and dates in quotes, numbers bare, and for lists, in [..]. Persistent fields only.
  • oslc.pageSize and nextPage: Small pages, then follow responseInfo.nextPage.href until there is none.
  • POST and properties: POST to the collection creates: 201 and a Location. properties: wonum,status,href sends fields back.
  • x-method-override: PATCH: POST to the record's href with this header to update it. Send only what changes.
  • patchtype: MERGE: Without it, a PATCH deletes child rows you did not send, like Sync. With it, it behaves like AddChange.
  • If-Match and 412: Send the ETag you read. 412 Precondition Failed means someone changed the record first: read again.
  • Actions: ?action=wsmethod:<name> on a record href, with x-method-override: PATCH. Workflows use workflow:<name>.
  • The rules guard the API too: Started work cannot be cancelled: INPRG to CAN is refused with a 400 that says why. Read it; never assume success.
  • BMXAA error: reasonCode, message, statusCode and a moreInfo link. Read the words twice, then look the code up.
  • Retry only 429 and 503: Wait longer each time, with a little randomness. Fix a 4xx instead of resending it.

Where these facts come from

Try it on the real tools

How did Level 5 go?

Rate the level and say what worked, what did not, what you liked and what you did not. Send it now, or with your full report.