Overview

The REST API provided by Matrix42 Service Management tool (ESM) enables integration of any external application with the Matrix42 solution. The REST API follows RESTful constraints and principles to enable access to the data in ESM. All system and data model administrative functionalities are excluded from the REST API interface. 

How to Get Started

REST API can be enabled in any Matrix42 environment with Matrix42 Service Management tool (ESM) updated to 2021.4 version or later. The enablement is done by requesting a REST API license for the environment from Matrix42. The license will enable Matrix42 External API module in the system. The system also needs to have a technical (local) user and a role defined for access management purposes.

Accessing the Environment

All endpoints related to REST API can be accessed from  [base_url]/rest-api/itsm/:versionCode (e.g. https://yourMatrix42environment.m42cloud.com/rest-api/itsm/v1/) in cloud-enviroments and  [base_url]/itsm/api/:versionCode 
Please note that REST API is not supported in on-prem deployments (Windows installation + MSSQL database).  You can easily test accessing the REST API Swagger documentation with your browser: Swagger UI can be accessed from [base_url]/rest-api/itsm/v1/docs/swagger/index.html (e.g., https://yourMatrix42environment.m42cloud.com/rest-api/itsm/v1/docs/swagger/index.html).

License

The environment needs to have a REST API license. When the license is in place and ESM is restarted, admin can check that the System status – System status and runtime information in the Admin view lists Matrix42 External API as one of the enabled modules.

Logging

The REST API calls will be logged to a file called “integration.log” available via the ESM admin view. The log includes all the operations done against the REST API. 
ESM also logs the statistics into separate log file called “Matrix42_rest_rest_api_usage.log” also available through the ESM admin view. 

2023-04-11 20:34:00,635|Usage,consumed,1000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-12 04:54:00,643|Usage,consumed,2000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-12 13:30:00,743|Usage,consumed,3000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-12 21:50:00,573|Usage,consumed,4000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-13 06:10:00,548|Usage,consumed,5000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-13 14:30:00,606|Usage,consumed,6000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-13 22:50:00,882|Usage,consumed,7000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-14 07:10:00,737|Usage,consumed,8000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-14 15:30:01,055|Usage,consumed,9000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-14 23:50:00,690|Usage,consumed,10000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-17 00:00:00,144|Usage,consumed,15779,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-17 00:00:00,145|Statistics reset

The above snippet is an example of “rest_api_usage.log” file. The log gives statistics on the weekly basis for successful and unsuccessful REST API calls with summary at the end of the weekly period. These successful calls are also called as REST API transactions.

Users

To authenticate any requests via the REST API, Matrix42 Service Management tool needs to have a local user account (i.e. not EIM account that is used in cloud environment for logins). A good practice is to create new user for each integration using the REST API. You also need to create a role which has permissions to use External API and give this role to the local user.
Creating valid account can be done with following steps:

1. Create role and select Matrix42 External API -module permission.
2. Add folder permissions to role.
3. Add template permissions to role.
4. Create REST-API user.
5. Add user to previously created role.
6. Test, that you can obtain JWT-token from login endpoint.

Authentication

REST-API uses JWT Bearer -tokens for authentication, which can be acquired from dedicated login endpoint. After token has been created, it is valid for predefined timespan which can be configured in ESM platform-setting security.external.api.token.expiration.time – default expiration time is 15 minutes. These tokens are non-blocking, meaning one account can generate as many tokens as needed.

A POST request can be used for acquiring the JWT-token: 

https://instance.Matrix42cloud.com/rest-api/itsm/v1/users/login

The login and password must be included in the request body. If username and password are valid, server responds with JWT-token in the headers.

Since ESM version 2022.3.0.2 the token is returned also in the body: 
{
"code": 200,
"message": "Token issued.",
"timestamp": "2022-10-13T10:14:15Z",
"token": "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJURVNUX1JFU1RBUEkiLCJpc3MiOiJodHRwczovL2VzbXBvci5lZmVjdGVjbG91ZC1kZXYuY29tL2l0c20vYXBpL3YxL3VzZXJzL2xvZ2luIiwiaWF0IjoxNjY1NjU2MDU1LCJleHAiOjE2NjU2NTY5NTV9.aO2Td-62f2QYNszZhc9rbM-MOs_zhZvnRuJXK28CLIApmj_p6O0oL7Dy623QsRZwR3AWrajzQ96uKYgFxzxvwg"
}

In subsequent requests to other endpoints token needs to be included in Authorization-header (similar format than it’s returned) for authorization. For example, getting all incidents could look like (if using curl):

GET "https://Matrix42cloud.com/rest-api/itsm/v1/dc/incident/data" -H  "accept: application/json" -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUcnlpbmcgdG8gZGVjb2RlIG91ciB0b2tlbnM_IiwiaWF0IjoxNjM4MzcyODM1LCJleHAiOjE2Njk5MDg4MzUsImF1ZCI6Ind3dy5leGFtcGxlLmNvbSIsInN1YiI6IlRoYXQncyBnb29kLCB5b3Ugc2hvdWxkIGFsd2F5cyB0aGluayBhYm91dCBzZWN1cml0eS4ifQ.zzdHvo6VvqN08-YCtylWQCQjcKI7L9TCgHWplOgnNXY

Tools

Swagger

Swagger, a tool for interacting with the API and viewing the documentation, is included in every environment that has valid REST-API license. Swagger UI can be accessed from base_url/rest-api/itsm/v1/docs/swagger/index.html (e.g., https://Matrix42cloud.com/rest-api/itsm/v1/docs/swagger/index.html).
Swagger generates documentation based on OpenAPI 3.0 specification, which can be also downloaded from the UI (base_url/rest-api/itsm/v1/docs/openapi.json) and imported to various integration and testing tools.

Settings

The following settings related to the REST API can be adjusted in the Matrix42 Service Management Tool. Please note that the settings are used for ensuring that integrations would not negatively impact the system’s performance. It is not recommended to increase the setting values, since that might allow integrations to cause unnecessary load.