Web Services: REST API integration

Details

Matrix42 Web Services provide a way to integrate any of the 3-rd party applications in order to get data into and out of the Matrix42 platform without recurring to the user interface.

Matrix42 Web Services are an HTTP-based REST API that other applications can use to programmatically query necessary data, create, manage and close tickets, incidents, manage orders and perform a large variety of other tasks and actions supported by the Martix42 platform.

Matrix42 Web Services imply exchanging data between applications thus it supports basic actions: create, read, update and delete (CRUD).

In this article, you'll learn the basics of the Matrix42 Web Services API to be able to integrate and use it effectively in your application.

Introduction

Matrix42 Web Services are REST APIs and this section will help you understand how it works.

API stands for Application Programming Interface. APIs define how two pieces of software communicate with each other.
REST: REpresentational State Transfer is a method for client devices (laptops, smartphones, computers, tablets etc.) and servers to pass data back and forth.

REST API consists of requests and responses flow:

API request: for instance, you need to know the status of a ticket or an incident. The client device using an application with integrated Matrix42 REST API sends a request to the Matrix42 application server;
API response: the server responds with the information by transferring specific data that represents the state of the requested field, in our case the ticket status.

So REST is a category of a web API. A web API defines how software systems communicate over the World Wide Web.

API types overview

Generally used API interface types are defined depending on data availability and whether it targets external or in-house application developers:

Matrix42 Administration application keeps all available for the Matrix42 platform APIs.

Provided by Administration application API types are:

Product API: is a type of a web API available for those organizations that have access to the Matrix42 platform. It's a mixed form of public and private APIs. It was designed to be used by the developers inside the Matrix42 application and at the same time, it can be accessed by other developers whose organizations use Martix42 platform for their business needs.

Public API : or an open API is an interface that is designed to be easily accessible for a larger audience of developers. In this way, open APIs are used not only by the developers of the Matrix42 platform and companies who use Matrix42 for running their business processes but also by any developers who wish to register for Matrix42 API access outside any of these organizations.

Characteristics

Characteristics/ API type	Public API	Product API	Description
Accessibility	✔️	✔️	both API types are available for all registered users of the Matrix42 Administration application.
Usability	✔️	✔️	API documentation and necessary parameters are available per each represented in the Administration application endpoint and its specific methods.
Security	✔️	✔️	all requests can be issued from the reliable resources only and require authentication.
Stability	✔️	❌	Public API is standardized, stable, reliable and application update-safe. Product API is provided for extensive usage in the same way as Public API but Product API is not standardized and can be a subject to the API's structure modification, changes, and updates as it was initially designed to ensure the application's functioning and not for external usage.

Stability: Public API

Public API endpoints and data retrieval for provided methods are stable, reliable and update-safe. Public API is not a subject to any changes made in the application architecture over time. It was designed as a solid and integral part of the application's ecosystem.

In case of any changes, including API updates, all Matrix42 platform users are notified beforehand, for instance via Release Notes. Possible API changes are introduced gradually and available endpoints and methods are not decommissioned at once. In these circumstances, there is always a necessary time-frame for the applications integration upgrade and data exchange flow modification in accordance with the newly introduced principles.

So the available Public API changes are introduced according to the commonly accepted flow:

Active → Deprecated →Obsolete → Decommissioned.

Stability: Product API

Product API is available for use to the same extent as the Public API with the main difference that Product API is more changes prone.

Product API can still be integrated with other applications, but it is not guaranteed that its availability, data structure or represented methods will always remain as is and won't be changed over time.

In any case, all application changes including API modification are timely conveyed to the parties concerned.

API types in the user interface

API call endpoints and detailed data description can be found via the Administration application → Integration menu.

Web Services

Web Services menu lists all available APIs, both product and public.

On this page you may find:

Product API: marks listed API as a Product API;
Public API filter: marks listed API as Public API;
API documentation: click on the item of the list to see details of the API request route and available methods preview.

Public API preview in the Web Services menu lists all available methods of a specific API:

Apply Public API filter;
Click on the item for a preview;
Public API shows all implemented methods: product and public.

Public API

Use Web Services menu → Public API for more accurate and precise filtering.

Public API page lists only public APIs and exclusively public methods as follows:

Open Public API page;
Select item for preview;
Preview a list of public methods.

All public methods are additionally marked with "Public" tag in the API preview.

By making API requests you retrieve or alter database data. In order to keep all the data safe, especially if it is company sensitive or financial data, each request should be issued from a verified and authenticated source.

Security: Authentication and Authorization

In order to use an API, the client device needs to prove to the server that it has the authority to receive or modify data.

Authentication is a verification of the credentials during the server connection attempt. It consists of sending the credentials from the client to the server side and proving that the requester is authentic by providing, for instance, a username and password or other data required by the used for the server authentication protocol.
Authorization: occurs after successful authentication and defines which resources are available for the authenticated party. At the same time, authorization may mean that the API request includes a special token that indicates to the server that the requester has the authority to make the request.

Authentication and authorization flow depends on the implemented approach. Matrix42 platform supports:

Basic Authentication: authentication method that requires providing user name and password when making a request;
API token: an application programming interface key which serves both as a unique identifier of an application requesting access to the server and a secret token for authentication.

For more information and examples see Web Services: Authentication types page.

REST API Requests

Implemented REST API is based on HTTP protocol, therefore each request consists of such parts:

Method: an action that should be performed on the requested resource;
Endpoint: path identifying the location of the requested API service;
Headers: request header containing authentication credentials and specifying the body content type ;
Body (optional): message or information that should be sent to the server. Applicable for the data modification requests with methods 'POST' or 'PUT'.

Methods

The method is the type of request that can be sent to the server. Generally used methods are:

Method name	Description
'GET'	retrieves a resource from a server. The server looks for data and sends it back in the response. 'GET' request performs a 'READ' operation.
'POST'	creates a new resource on the server. By performing a 'POST' request, the server creates a new entry in the database and tells in response whether the creation is successful. 'POST' request performs 'CREATE' operation.
'PUT'	update an existing resource on the server. By performing a 'PUT' or 'PATCH' requests, the server updates an entry in the database and tells in response whether the update is successful. 'PUT' request performs 'UPDATE' operation.
'DELETE'	deletes a resource from the server. By performing a 'DELETE' request, the server deletes an entry in the database and tells in response whether the deletion is successful. 'DELETE' request performs 'DELETE' operation.

Endpoints and request URL

Endpoint is the context path identifying the location of the requested API service on a specific server.

The following URL structure of the Matrix42 Public API identifies a complete path to a requested resource:

https://<hostname>/m42Services/<endpoint>

Where:

hostname is a Base URL of an application: martix42.com;
m42Services stands for the service name which provides REST API;

Out of the box version of the Matrix42 platform provides this service under 'm42Services' name, although if necessary it can be customized and manually changed by the network environment administrator. These changes are not applied via the user interface of the Matrix42 platform.

endpoint is a path to a requested resource.

Request URL example:

https://martix42.com/m42Services/api/data

Headers

This section lists available HTTP request headers:

Header	Description	Required
Authorization: <type> <credentials>	specifies request authentication credentials. Possible types: Basic (not recommended): contains base64 encoded username and password joined by a colon, for example: Authorization: Basic YWzhZARabpvcGDuc2sYW1l API token (recommended): request credentials include an access token generated based on the API token, for example: Authorization: Bearer <access token>	Required
Host: <host name>	the domain name of the server where the necessary resource is located	Required
Content-Type: application/json;charset=UTF-8	specifies the media type of the retrieved resource and character encoding standard. Required for 'PUT' and 'POST' methods.	Optional
Explicit-Language: <language tag>	a header field containing language tag that should be represented in and supported by Matrix42 applications. Specifies the retrieved content language. Syntax: en, de, fr: two-letter or a three-letter lowercase abbreviation of a language code according to ISO 639 standard; en-US, de-DE, fr-CA: language code followed by an optional sub-code of a country where this language is spoken. See ISO 3166 for a list of country codes; not specified: if the explicit language is not specified the response is retrieved based on the application language which is currently selected in the profile of the user who has generated the API token; Accept-Language header is ignored and results in the same response as if it was not specified. If it is set in the request header the returned content is in the language which is currently selected for the user profile of the Matrix42 application	Optional

Body

Body is a message or information that should be sent to the server. Body is applicable for the data modification requests with methods 'POST' or 'PUT'.

API documentation

Comprehensive documentation with a detailed list of required body parameters is provided in the Administration application user interface:

Open Administration application → Web Services → Public API page;
Click on the Public API service name for details;
Click on the method name for detailed request preview;
Request documentation specifies the method, endpoint, query parameters, and required body parameters;
Used types section enumerates all required and optional body parameters and their types;
Code example generates and downloads a .txt file with a request example in JavaScript and C# languages. The file includes a code sample containing method, URL, headers including authentication and request body if present.
Show audience clickable link shows current API service access restrictions. Audience restriction rules may cause a '403 Forbidden' error as a result of a well-formed request made by an authenticated user due to the restricted user role permissions. Audience restriction can be manually set for a specific method and for the entire API enpoint.

Error handling

Responses are based on standard HTTP status codes:

2xx: Success indicates a successfully submitted by the client and accepted by the server request;
3xx: Redirection informs that some additional actions should be performed by the client in order to complete the request;
4xx: Client Error is an error status code category informing of the issues possibly caused by the client, such as required authentication, authorization restrictions, not supported methods etc.
5xx: Server Error indicates an API service malfunctioning due to internal server errors.

Request body JSON format

The body of a request that requires body message must be a well-formed JSON.

Errors caused by the invalid syntax of a JSON format are not processed and handled in any way.