AMAGE REST API Interface - Execution Supervision

Introduction/Context

Context for operations on Supervision module objects in the AMAGE system, which should be extended with the appropriate method in the query.

  • rest/amage/v1/supervisions

Data structures

Structures and data types used in queries and responses.

Result:

The ID/UUID fields contain the identifier of the newly created or edited object. If the operation is performed correctly, the success field is set to true. If an error occurs, the success field is set to false, and the message field contains a description of the error. The error code then contains an HTTP code of the NOT_FOUND or BAD_REQUEST type. The BAD_REQUEST code is also returned in the query. Depending on the type of error during query processing, the error code may be different than the main query code returned. The query code will be BAD_REQUEST, and the internal code will be set to NOT_FOUND in the case when the query sets an object property to another object in the system. The JSON parameter will be correct (record UUID), but there will be no such record in the system. Therefore, the NOT_FOUND code will appear in the errorCode field. In the message description field, a message informing what record was not found, and the main query error code will be BAD_REQUEST.

{
    "id": 1,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Source of information. Enumerated field as a comma-separated list of values. Available values:

  • FROM_DESKTOP,

  • FROM_MOBILE,

  • FROM_IDENTIFIER,

  • FROM_DIFFERENCE,

  • FROM_IMPORT,

  • FROM_WEB_SERVICE,

  • FROM_DATA_AGGREGATOR,

  • FROM_AUTOMATION

API operations

Getting the number of supervision items

  • Method: GET

  • Path: /count

  • Generates: text/plain

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Returns the number of all supervision items in the system.

{
    123456
}

Downloading the list of supervised items

  • Method: GET

  • Path: /list

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • page - RequestParam - page - counted from 1

  • size - RequestParam - page size - number of records per page, we suggest limiting it to 1000 items. Depending on the API implementation, the value may be limited to a smaller number.

The returned data is an array of JSON objects with the structure:

{
  "id": 12345,
  "uuid": "a7de192f-e9c4-4ff9-9875-95f1144665c3",
  "productUuid": "a7de192f-e9c4-4ff9-9875-95f1144665c3",
  "active": true,
  "stateTemplateUuid": "a7de192f-e9c4-4ff9-9875-95f1144665c3",
  "stateTemplateItemUuid": "a7de192f-e9c4-4ff9-9875-95f1144665c3",
  "progress": 100,
  "currentCount": 10
}
In the case of downloading data from the system, the ID/UUID field will be populated in the returned structure with data from the system. The ID field is the identifier of the local database. The UUID field is a global identifier in the AMAGE system, which can serve as an identifier uniquely identifying an object in the system and in integrations between systems.

Getting a supervision item by UUID

  • Method: GET

  • Path: /get/by-uuid/{uuid}

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • UUID - supervised element identifier

The data returned is a single JSON object with an element type structure identical to the /list method.

Initializing a new supervision element

  • Method: POST

  • Path: /init/{product-uuid}/{template-uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Initializes a new supervision item. Requires the product UUID and the state template UUID. If a supervision for a given template exists for the given resource, then an operation result object is returned with the BAD_REQUEST code and information about a potential duplicate record.

Query content (body) is empty.

Query

/rest/amage/v1/supervisions/add/9cefca39-0d18-47ec-ab26-c694e5aec7ce/5de59aac-e704-424d-ab30-5d5d7693ff3c

Response

{
    "id": 12345,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Removing a supervision element

  • Method: DELETE

  • Path: /delete/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • UUID - supervised element identifier

Query content (body) is empty.

Query

/rest/amage/v1/supervisions/delete/f25e62ea-0100-4f4e-aad2-853cf48df2b9

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Reading the supervision history record data

  • Method: GET

  • Path: /history/{uuid}

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • UUID - history entry identifier for the supervised item

The returned data is a JSON object with a structure:

{
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "invalid":false,
    "timestamp":"2021-01-01T12:00:00",
    "supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "progress":100,
    "addedCount":0,
    "locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "mapShapeLatitude":50.0,
    "mapShapeLongitude":20.0,
    "mapShapeMapCode":"default",
    "parameters":[
        {
            "id": 3456,
            "parameterSettingUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "date": "2021-01-01T12:00:00",
            "userUuid": "1c4066e6-cdd6-4903-803a-b6bffe689527",
            "currentValue":"100.0",
            "source":"FROM_WEBSERVICE"
        }
    ]
}
In case of retrieving data from the system, the ID and UUID fields will be filled in the returned structure with data from the system. The ID field is the local database identifier. The UUID field is a global identifier in the AMAGE system, which can be used as an identifier that uniquely identifies an object in the system and in integrations between systems.

Saving history to an existing supervised item

  • Method: POST

  • Path: /add-history/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • UUID - supervised element identifier

The query body should contain a JSON object with monitoring history data. The object has the following structure:

{
    "invalid":false,
    "timestamp":"2021-01-01T12:00:00",
    "supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "progress":100,
    "addedCount":0,
    "locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "mapShapeLatitude":50.0,
    "mapShapeLongitude":20.0,
    "mapShapeMapCode":"default",
    "parameters":[
        {
            "id": -1,
            "parameterSettingUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "date": "2021-01-01T12:00:00",
            "userUuid": "1c4066e6-cdd6-4903-803a-b6bffe689527",
            "currentValue":"100.0",
            "source":"FROM_WEBSERVICE"
        }
    ]
}

Query

/rest/amage/v1/supervisions/add-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}
When saving data from the system, the ID field cannot be filled in. It is filled in when saving the record to the database and returned in the response structure. If the UUID field is provided, then such a value will be assigned to the record. The system does not check the uniqueness of the UUID within the structures or context of the entire system. If the UUID is not provided, the system will generate its own unique UUID.

Editing supervision history

  • Method: POST

  • Path: /edit-history/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • UUID - supervision history identifier

Due to operations on existing data, changes in related parameters are not included in the edit. The parameters remain unchanged. We only modify the parameters of the main object of supervision history.

The query body should contain a JSON object with monitoring history data. The object has the following structure:

{
    "invalid":false,
    "timestamp":"2021-01-01T12:00:00",
    "supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "progress":100,
    "addedCount":0,
    "locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "mapShapeLatitude":50.0,
    "mapShapeLongitude":20.0,
    "mapShapeMapCode":"default"
}

Query

/rest/amage/v1/supervisions/edit-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Deletion of supervision history

  • Method: DELETE

  • Path: /delete-history/{uuid}

  • Generates: application/json

  • Requires: application/json

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • UUID - supervision history identifier

Query content (body) is empty.

Query

/rest/amage/v1/supervisions/delete-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}

Examples

Sample Python code using the requests library to add supervision history.

#!/usr/bin/python3

import binascii
import hashlib

import requests

PARAM_SEPARATOR = ";"

def calc_api_sign(path, api_secret):
    message_digest = hashlib.sha256()
    message_digest.update(bytearray.fromhex(api_secret))
    message_digest.update(PARAM_SEPARATOR.encode('utf-8'))
    message_digest.update(path.encode('utf-8'))
    return message_digest.digest()

def post_method(server_url, headers, path, json):
    print(server_url + path)
    url = server_url + path
    response = requests.post(url, headers=headers, json=json)
    print("received return code: {0}".format(response.status_code))
    print("received data: {0}".format(response.text))

def get_header(path, content_type, accept):
    headers = {
        "Content-Type": content_type,
        "Accept": accept,
        "amage-device-uuid": device_uuid,
        "amage-api-key": api_key,
        "amage-api-sign": binascii.hexlify(calc_api_sign(path, api_secret)).decode()
    }
    return headers

server_url = "https://server.url/rest/amage/v1/"

device_uuid = "b0b135db-14f7-4d35-92d8-8357815185df"
api_key = "f4affb2db24b2b0903ad89ceeb622ece"
api_secret = "f4affb2db24b2b0903ad89ceeb622ede"

supervision_state_item_uuid = '1ba796f7-4a56-4ce1-ad6c-6d9c528974ad'
supervision_element_uuid = '1c4066e6-cdd6-4903-803a-b6bffe689527'
parameter_setting_uuid = '1c4066e6-cdd6-4903-803a-b6bffe689528'

request_path = "supervisions/add-history/" + supervision_element_uuid;

#ItemSource available values:
#    FROM_DESKTOP,
#    FROM_MOBILE,
#    FROM_IDENTIFIER,
#    FROM_DIFFERENCE,
#    FROM_IMPORT,
#    FROM_WEB_SERVICE,
#    FROM_DATA_AGGREGATOR,
#    FROM_AUTOMATION

1json = {
    'invalid': False,
    'timestamp': '2024-10-06T12:00:00',
    'supervisionElementUuid': supervision_element_uuid,
    'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185de',
    'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
    'progress': 100,
    'addedCount': 1,
    'mapShapeLatitude': 0,
    'mapShapeLongitude': 0,
    'mapShapeMapCode': 'default',
    'parameters': [
        {
            'date': '2024-10-06T12:00:00',
            'parameterSettingUuid': 'e3588070-5ccf-47fa-aa9d-e7ca0b929d90',
            'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185de',
            'currentValue': '99',
            'source': 'FROM_WEB_SERVICE'
        }
    ]
}

post_method(server_url, get_header(request_path, "application/json", "application/json"), request_path, json)

Example execution

Example query results for adding supervision history.

json = {
    'invalid': False,
    'timestamp': '2024-10-06T12:00:00',
    'supervisionElementUuid': supervision_element_uuid,
    'userUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
    'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
    'progress': 100,
    'addedCount': 1,
    'locationUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
    'mapShapeLatitude': 0,
    'mapShapeLongitude': 0,
    'mapShapeMapCode': 'default',
    'parameters': [
        {
            'date': '2024-10-06T12:00:00',
            'parameterSettingUuid': 'e3588070-5ccf-47fb-aa9d-e7ca0b929d90',
            'userUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
            'currentValue': '99',
            'source': 'FROM_WEB_SERVICE'
        }
    ]
}

Incorrect location UUID:

httpd://server.url/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 400
received data: {"id":null,"uuid":null,"success":false,"errorCode":400,"message":"Location not found with UUID: 75d2b25d-4698-48b9-bb62-7569ffb763fc"}

Invalid user UUID, no location:

/usr/bin/python3 example_supervision.py
http://localhost:8000/assetweb/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 400
received data: {"id":null,"uuid":null,"success":false,"errorCode":400,"message":"User not found with UUID: 75d2b25d-4698-48b9-bb62-7569ffb763fc"}

Correct data:

1json = {
    'invalid': False,
    'timestamp': '2024-10-06T12:00:00',
    'supervisionElementUuid': supervision_element_uuid,
    'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185df',
    'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
    'progress': 100,
    'addedCount': 1,
    'mapShapeLatitude': 0,
    'mapShapeLongitude': 0,
    'mapShapeMapCode': 'default',
    'parameters': [
        {
            'date': '2024-10-06T12:00:00',
            'parameterSettingUuid': 'e3588070-5ccf-47fb-aa9d-e7ca0b929d90',
            'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185df',
            'currentValue': '99',
            'source': 'FROM_WEB_SERVICE'
        }
    ]
}
/usr/bin/python3 example_supervision.py
http://server.url/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 200
received data: {"id":1000816683,"uuid":"d020d04c-756c-453e-8458-28590dc5c0fa","success":true,"errorCode":0,"message":""}

Process finished with exit code 0