Find the right Maximo REST and JSON API documentation

Maximo has more than one REST interface, and calling all of them “the JSON API” makes it easy to read the right documentation for the wrong endpoint. The first thing to identify is the Maximo version and URL used by the integration.

The resources below cover API comparison, overview, querying, CRUD and advanced features. They use maintained IBM documentation alongside legacy guides that remain useful for older systems.

Choose the API generation first

The hostname and /maximo context can differ in a real environment. Identify the endpoint from the integration configuration rather than assuming the default context root.

Legacy Maximo 7.5 REST API

The legacy API can return XML or JSON, but its URLs, request parameters, response shape and write operations differ from the newer REST/JSON API. A request commonly starts with an MBO or object-structure resource under /maxrest/rest:

GET https://<host>/maxrest/rest/mbo/ASSET?_format=json

Use the Maximo 7.5 Integration Framework guide for the authoritative legacy reference. The local article Use JSON with the legacy Maximo 7.5 REST API provides a worked example and explains why its URL-based password authentication should remain confined to controlled legacy testing.

Do not silently move an existing /maxrest client to /oslc. Field selection, paging, authentication, error responses and create or update semantics all need regression testing.

Maximo 7.6 REST/JSON API

IBM added the newer REST APIs in Maximo 7.6.0.2. They evolved from the legacy interface, provide end-to-end JSON support and remove the requirement to use OSLC namespaces in ordinary JSON payloads. Object structures are exposed below /oslc/os:

GET https://<host>/maximo/oslc/os/mxapiasset

The REST JSON API enhancements overview is the quickest feature map. It covers related-object queries, text search, custom queries, JSON schemas, dynamic query views, grouping, custom JSON elements, Swagger documentation and JSON, XML or CSV interchange.

For release-specific details, use the Maximo 7.6.1 Integration Framework guide. It keeps the API behaviour tied to the traditional Maximo version you are maintaining instead of assuming every option in current Manage exists there.

Current Maximo Manage API reference

The Maximo Manage REST API reference is the practical starting point for a current integration. It lists the published API object structures and their supported collection, member, create, update and delete operations.

Use the reference to confirm:

• the object structure name and resource path;
• request headers and accepted content types;
• supported query parameters;
• create, update and delete behaviour;
• response codes and error documents; and
• the fields exposed by that API object structure.

The online reference can display parameters used only in particular releases or authentication configurations. Confirm each option against the exact Manage release and deployment security model before putting it into shared client code.

Querying and selecting data

Start a query from the collection resource for an object structure:

GET https://<host>/maximo/oslc/os/mxapiasset?lean=1

Then use the query and response-selection options documented for your release. These commonly cover predicates, selected properties, paging, ordering, saved queries and related records. Request only the fields and rows the client needs; an unconstrained collection request can produce unnecessary database load and large responses.

When you need the JSON schema for an API object structure, use the schema endpoint documented by the installed release. Schemas help a client discover field types and structure, but they do not replace Maximo authorization or business-rule validation.

Creating, updating and deleting records

The newer API accepts JSON request bodies. A create request uses POST on the collection resource:

POST /maximo/oslc/os/mxapiasset?lean=1
Content-Type: application/json
Accept: application/json
 
{
  "assetnum": "TESTASSET1",
  "siteid": "TEST",
  "description": "Disposable API test asset"
}

Use the member URL returned by Maximo for later reads or changes. The supported update method, method-override headers and delete behaviour depend on the API version and client constraints, so follow the operation shown for that resource in the API reference.

Test writes with a dedicated integration user, minimum required permissions and disposable data in a non-production environment. Check the HTTP status and response headers as well as the JSON body, then verify the result through Maximo. A successful HTTP exchange does not prove that downstream automation, integration events or security restrictions behave as intended.

Authentication and API keys

For a headless current integration, use the authentication model supported by the deployment. IBM documents API keys for inbound machine-to-machine access and explains the differences between /oslc and the API-key-enabled /api mapping for application-server-authenticated environments.

Read IBM's API key guidance before creating or distributing a key. An API key acts with its Maximo user's permissions, so use a dedicated account, restrict its security groups, store the key in a secrets manager, rotate it and never place it in source control or a URL copied into documentation.

A useful reading order

For a new integration:

1. Confirm the Maximo or Manage version and endpoint family.
2. Read the overview for that API generation.
3. Find the intended API object structure in the reference.
4. Review authentication before building example requests.
5. Test a small, field-limited GET request.
6. Retrieve the schema and confirm the response contract.
7. Add create or update operations only after defining permissions, validation, retry and duplicate-request behaviour.
8. Record the product version and API assumptions alongside the client code.

That sequence is more reliable than combining examples from legacy /maxrest, newer /oslc and current /api documentation into one client.

References

• IBM: Integration APIs in Maximo 7.6
• IBM: REST JSON API enhancements
• IBM Developer: Maximo Manage REST API reference
• IBM: API keys