Introduction to AMAGE programming interfaces

Introduction

The document describes AMAGE programming interfaces that enable integration with the AMAGE system. Interfaces allow access to data and to perform operations on data in the AMAGE system. Communication is carried out via the HTTPS protocol and REST API methods. To use AMAGE programming interfaces, you must have appropriate access rights and access keys.

Generation of access keys - summary

The application uses access keys (APIKeys) to create shortcuts authorizing access to the WEB REST API interface. We define key permissions in the configuration interface in the API Keys section.

Figure 1. View of the API key list with basic information about the key

Figure 2. API key access details

For more, refer to the user manual:

API Keys - User Guide.

API keys, authorization and data headers

To enable access to the API and be able to communicate through this interface, we need to create API keys for authorizing/signing queries so that the AMAGE system is able to correctly recognize the query and share the data. Generate API keys in the configuration section and don’t forget to activate it. Save three parameters - device-uuid, key and secret, which will be used to generate the query signature.

API Key Configuration Documentation

Object identification/UUID

Objects in the system identify themselves by their unique UUID. In order to download an object from the system, you need to know its UUID. UUID can be found in the user interface, in export files, in the database, in system logs. Typically, in the user interface, an additional button with an (I) icon appears for each object in the data viewer or its editor. After selecting it, information about the object’s identification data, including UUID, is displayed. Use this UUID for interactions where a UUID is required.

Figure 3. Information button

Figure 4. Identification data including UUID

API signature

For each communication with the AMAGE system through the REST interface, three headers (headers) with data are required:

amage-device-uuid - identifier of the device for which the signature is generated
amage-api-key - API key
amage-api-sign - query signature

Device UUID and API key are provided directly from the generated API key. The signature is generated based on the query path and the API key secret. The signature is generated using the SHA-256 algorithm and the result is transmitted in binary form. The result is then converted to hexadecimal and passed as an amage-api-sign header.

In the case of queries that contain parameters in their content (URL), remember that to calculate the query signature we use only the query path itself, without parameters. That is, for the path rest/api/v1/test/query?param1=1&param2=2 we calculate the signature for the path rest/api/v1/test/query.

For an example of calculating a query signature in Python, see the individual examples for each interface section.

Kodowanie znaków

Wszelkie znaki w zapytaniach powinny być odpowiednio zakodowane. W przypadku zapytań GET znaki powinny być zakodowane zgodnie z zasadami URL Encoding.

W przypadku zapytań POST, znaki powinny być zakodowane zgodnie z zasadami JSON Encoding.

Programming interfaces

The available information about REST APIs is divided into functional sections. After appropriate authorization, the user can use individual sections.

Select a section/article:

AMAGE REST API Interface - Attachments:: The document describes the case of adding serial numbers to devices/materials already delivered to the destination. Using the delivery editor in the Desktop view, we can add inventoried serial numbers.
AMAGE REST API interface - report generation:: The document describes the generation of reports from the AMAGE system. Reports can be generated in PDF, XLSX, JSON format with full use of report tabs to generate reports according to user requirements.
AMAGE REST API Interface - Execution Supervision:: The document describes the interface and functions of execution supervision in the AMAGE system - Supervision module.
AMAGE REST API - Work Orders:: The document describes the interface and functions related to work orders in the AMAGE system - Work Orders module.
AMAGE REST API - Resources/Parameters:: This document describes the interface and functions related to resource objects and related elements in the AMAGE system - Structure module.
Interfejs REST API AMAGE - typy elementów:: Dokument opisuje interfejs i funkcje powiązane z typami elementów, parametrami oraz szablonami parametrów w systemie AMAGE - moduł Structure.