Data REST API Developer's Guide

Edit online

The IBM® Maximo Inventory Optimization Data REST API Developer's guide explains how to use and apply the REST Data APIs.

Introduction

The REST-based APIs are available for interaction with the IBM Maximo Inventory Optimization Data application.

Accessing the Data API

To access the Data API reference documentation, go to IBM Maximo Inventory Optimization Data API.

Data Integration

Data needs to be moved between the ERP and IBM Maximo Inventory Optimization to allow for analytics and optimization to be run. The Data API provides the interface for developers to seamlessly communicate between their ERP and IBM Maximo Inventory Optimization Inventory with HTTPS.

The Data Download APIs retrieve changes exported out of IBM Maximo Inventory Optimization for integration into the client ERP. They are also used to trigger a daily or monthly data refresh, and load data back to IBM Maximo Inventory Optimization.

Using API extracts and exports makes them more efficient and securely automated.

What is an API?

API stands for Application Programming Interface, by using an API, functions within an application are made available outside of that product to other applications. APIs are interfaces that are made for two pieces of software to interact together.

Public APIs allow developers to work on behalf of the customer to integrate IBM Maximo Inventory Optimization with other internal or external systems.

To use APIs allows users to integrate IBM Maximo Inventory Optimization software into their own business processes and allows for a more efficient automation of those processes.

The site.data.keyword.iot_mmio_full_notm APIs are implemented as RESTful web Services. REST (representational state transfer) is a software architecture style. REST is bound by specific constraints, including communicating over the HTTP protocol, making it relatively stable to program for.

What can you do with the Data APIs?

Sending data

Using the IBM Maximo Inventory Optimization APIs allow for connectors to automatically forward data to IBM Maximo Inventory Optimization. Each MIO data type has an associated API endpoint.

Refreshing data

Data can be refreshed on a daily or End Of Month (EOM) basis. The data refreshes requests can be further automated through IBM Maximo Inventory Optimization.

Apart from initiating and carrying out the data refresh it is also possible to check on the progress of the data refresh. The data refreshes ensure that any corrupted transfers can be deleted and repeated until successful.

Retrieving data

Retrieval of exported data sets can also be automated, ensuring that all information on hand is accurate and up-to-date.

Deleting data

If it failed transfers or uploads, requests can be made to delete specific payloads.

Security

The IBM Maximo Inventory Optimization APIs use the HTTPS protocol (Hypertext Transfer Protocol Secure). The protocol encrypts communication over the internet, requiring authentication and protecting the privacy and integrity of the data.

Authentication requires an API key. The API's authentication is specific to the environment so that where the client has access to more than one environment, different API key credentials are needed.

A client-specific key is generated per environment. The API key that is used for the sandbox environment would be different from the API key that is used to access the production environment.

  • Authentication is with an API key.
  • The API key is a minimum of 32 characters that consists of numbers, uppercase letters, and lowercase letters. The API key can be changed with a support request.
  • The Maximo Inventory Optimization API is behind a web application firewall (WAF). The rules in place restrict high volume-repeated requests, mitigating against a brute force attack and DDOS.
  • Communication encrypted over HTTPS.
Note: Anyone who knows this password can interact with the APIs, so it is necessary that the client keep these passwords secure.

Reference Documentation

Reference Documentation on the use of the API endpoints is available. Developers can interact with the Swagger UI interface of the API at IBM Maximo Inventory Optimization Data API.
Note: Interaction with some endpoints requires authorization credentials.

What’s Available in the Reference Documentation?

  • Brief descriptions of the end points
  • Parameter designation
  • Example Curl commands
  • Input format information
  • Response formats
  • HTTP Status and Error codes The response format of the APIs is JSON (JavaScript Object Notation). Some of the endpoints can also require a JSON Request Body.

What does your program need to do?

A suggested series of steps are followed when using IBM Maximo Inventory Optimization APIs to extract the most benefit from its use. These steps are outlined as follows.

  • ERP extract and upload to Maximo Inventory Optimization
    1. Extract data from your ERP/EAM to API format. For more information, see How To Configure .CSV Extracts for Upload.
    2. Place all files into a single .zip file.
    3. Upload .zip file to /dataapi/upload/zip endpoint.
    4. Ensure the .zip file uploaded successfully.
  • MIO export and download
    1. Periodically query the download endpoint. Frequency tees decided by business users. Recommendation is every hour. Frequency is not to be more than 24 hours.
    2. Download export .zip file.
    3. Extract contents of .zip file.
    4. Import changes from text file into ERP/EAM
Note: Ensure, throughout the process, that errors are being identified and handled.

EOM (End of Month) Refresh

Your software takes various extracts from your ERP and uses the IBM Maximo Inventory Optimization API endpoints to upload these extracts to IBM Maximo Inventory Optimization for processing. At month end, data refreshes are necessary to ensure data integrity between the ERP and IBM Maximo Inventory Optimization.

The EOM Refresh is called by issuing a POST request to the EOM endpoint:

POST /refresh/eom

Check for completeness by issuing a GET request to the Status endpoint.

GET /refresh/status

Download MIO Recommendations

When recommendations are exported from Maximo Inventory Optimization, they are in a ready to download state. If needed, it’s possible to see whether downloads are available without downloading by using the Available Downloads endpoint.

GET /download/available.

Different exports are available from Maximo Inventory Optimization, for example: Reorder Levels, and Lead time. During the software implementation phase, the users of Maximo Inventory Optimization, decide which export to use. At the minimum, the reorder levels export from Maximo Inventory Optimization is implemented.

To download the recommendations exported from Maximo Inventory Optimization, send a GET request to the Downloads endpoint, along with the code of export type you want to download.

Note: The codes to be used for the parameter exportTypeCode are provided by the IBM consultant who supports the implementation process. Please ensure you consult with the IBM consultant to obtain the correct codes for your specific configuration.

GET /download/{exportTypeCode}.

A .zip file that contains a CSV file for each of the export profiles in the specified export type is returned. Only new batches (batches that are not downloaded) are included.

Error Handling

Failed Upload

When a file is sent to one of Upload APIs, the response always returns a unique identifier, which is referred to as the Payload ID. Upon receipt of the file, the API quickly validates the format of the file. If an error is found, an error code is returned with the Payload ID.

If an error code is returned for an upload, you need be sure to rectify the problem with the following steps.

  • Make a DELETE call to the Upload API.
    • Supply the Payload ID of the failed upload.
    • DELETE /upload/{payLoadID}.
  • This is done to ensure that the extract is not included in the next data refresh.
  • Upload the affected extract again.
  • Make a GET call to the Upload Status endpoint to ensure that the upload was successful.
  • GET /upload/status/{payloadID} .

Failed Data Refresh

If a data refresh fails (either an EOM or a delta refresh run), a database restore is needed.

IBM Support is necessary to resolve this issue, so it is suggested that you get in touch with IBM Maximo Inventory Optimization Support team.

Configuring .CSV Extracts for Upload

The Data Upload API controller endpoints allow IBM Maximo Inventory Optimization clients to upload appropriate .CSV files. The records in these files are processed and applied to their respective input tables.

For more information, see reference article Data Upload API.

For clients to be accurately guided as to the configuration of the .CSV files, they can make GET calls to the same Data Upload endpoints. Calls cannot be made for Connector, Status, and Delete endpoints.

Example Request - GET request to the Activity Upload API

Example Request - GET request to the Activity Upload API 
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer ZGVtbzo4MTdlYWU3MDFkMjQ1YmE4NzMzZGIyZDEzZmZhMzZhZQ'

Making a GET request to the Data Upload API endpoints provides a JSON reply.

The reply is an object array that lists the fields to be included in the corresponding .CSV upload file. The reply indicates which fields are mandatory, and which fields are optional.

Example Response from earlier GET Request

  [
  {
  "column": "DIVISION",
  "mandatory": true
  },
  {
  "column": "PKG_HDR_NO",
  "mandatory": true },
  {
  "column": "DISTRICT_CD",
  "mandatory": true
  },
  ...
   ]

Looking at the provided example, you now know that the .CSV file to be uploaded by using the Activity Upload API endpoint has DIVISION, PKG_HDR_NO and DISTRICT_CD fields. These fields must be present in the file, as they are listed as mandatory.

By making GET calls to each Data Upload (except for Connector, Status and Delete endpoints), developers can be guided as to how best to configure their extracts.

For further reference, see Get Column API.

Rules For Uploads (.CSV Extracts)

Files (Extracts) that are to be uploaded to IBM Maximo Inventory Optimization the Data Upload APIs need to adhere to some specific rules:

  • They must be UTF-8 encoded.
  • The first row of the file must be the header column names.
  • The specific column names are dependent upon which endpoint that you are uploading to.
  • The number of fields in each row must match the number of fields in the header.
  • Double quotation marks are to be used as a text qualifier.
Note: However, adhering to the outlined rules is necessary for file validation files that pass validation can still have errors that prevent complete processing. Always check for error responses.